diff --git a/docs/zh-CN/plugins/sdk-runtime.md b/docs/zh-CN/plugins/sdk-runtime.md index fa34e8844..d09970567 100644 --- a/docs/zh-CN/plugins/sdk-runtime.md +++ b/docs/zh-CN/plugins/sdk-runtime.md @@ -1,28 +1,28 @@ --- read_when: - - 你需要从插件调用核心辅助方法（TTS、STT、图像生成、web 搜索、子智能体、节点） + - 你需要从插件中调用核心辅助函数（TTS、STT、图像生成、网页搜索、子智能体、节点） - 你想了解 `api.runtime` 暴露了什么 - - 你正在从插件代码访问配置、智能体或媒体辅助方法 + - 你正在从插件代码中访问配置、智能体或媒体辅助函数 sidebarTitle: Runtime helpers -summary: api.runtime —— 可供插件使用的注入式运行时辅助方法 -title: 插件运行时辅助方法 +summary: api.runtime —— 可供插件使用的注入式运行时辅助函数 +title: 插件运行时辅助函数 x-i18n: - generated_at: "2026-04-27T12:55:00Z" + generated_at: "2026-04-27T13:19:45Z" model: gpt-5.4 provider: openai - source_hash: bce429c28ce1cd5e888c757af314bc83e0236d4cf4ddf844948eea22d0ad0259 + source_hash: dfd306203375c1a11e67f7e0e28b3cd7f15924457fa80d801cf99ae6dc8c26fa source_path: plugins/sdk-runtime.md workflow: 15 --- -注入到每个插件注册流程中的 `api.runtime` 对象参考。请使用这些辅助方法，而不是直接导入宿主内部实现。 +每个插件在注册期间都会注入 `api.runtime` 对象，本页提供其参考说明。请使用这些辅助函数，而不是直接导入宿主内部实现。 - 在渠道插件场景中结合上下文使用这些辅助方法的分步指南。 + 分步指南，在渠道插件的上下文中使用这些辅助函数。 - 在提供商插件场景中结合上下文使用这些辅助方法的分步指南。 + 分步指南，在提供商插件的上下文中使用这些辅助函数。 @@ -34,23 +34,23 @@ register(api) { ## 配置加载与写入 -优先使用已传入当前调用路径的配置，例如注册期间的 `api.config`，或渠道/提供商回调上的 `cfg` 参数。这样可以让同一个进程快照贯穿整个工作流程，而不是在热点路径上重复解析配置。 +优先使用已经传入当前调用路径的配置，例如注册期间的 `api.config`，或渠道 / 提供商回调中的 `cfg` 参数。这样可以让同一个进程快照贯穿整个工作流程，而不是在热点路径中重复解析配置。 -仅当某个长生命周期处理器需要当前进程快照且没有配置传入该函数时，才使用 `api.runtime.config.current()`。返回值为只读；编辑前请先克隆或使用变更辅助方法。 +仅当某个长生命周期处理器需要当前进程快照，且该函数未传入配置时，才使用 `api.runtime.config.current()`。返回值为只读；编辑前请先克隆或使用变更辅助函数。 -工具工厂会收到 `ctx.runtimeConfig` 以及 `ctx.getRuntimeConfig()`。如果工具定义创建后配置可能发生变化，请在长生命周期工具的 `execute` 回调中使用 getter。 +工具工厂会收到 `ctx.runtimeConfig` 和 `ctx.getRuntimeConfig()`。如果某个长生命周期工具的 `execute` 回调中，配置可能在工具定义创建后发生变化，请在回调内部使用这个 getter。 -使用 `api.runtime.config.mutateConfigFile(...)` 或 `api.runtime.config.replaceConfigFile(...)` 持久化更改。每次写入都必须选择显式的 `afterWrite` 策略： +使用 `api.runtime.config.mutateConfigFile(...)` 或 `api.runtime.config.replaceConfigFile(...)` 持久化变更。每次写入都必须选择一个明确的 `afterWrite` 策略： - `afterWrite: { mode: "auto" }` 让 Gateway 网关重载规划器自行决定。 - `afterWrite: { mode: "restart", reason: "..." }` 当写入方明确知道热重载不安全时，强制执行一次干净重启。 -- `afterWrite: { mode: "none", reason: "..." }` 仅当调用方负责后续处理时，才抑制自动重载/重启。 +- `afterWrite: { mode: "none", reason: "..." }` 仅当调用方负责后续处理时，才抑制自动重载 / 重启。 -变更辅助方法会返回 `afterWrite` 以及类型化的 `followUp` 摘要，以便调用方记录日志或测试自己是否请求了重启。Gateway 网关仍然掌握该重启实际何时发生的控制权。 +这些变更辅助函数会返回 `afterWrite` 以及带类型的 `followUp` 摘要，调用方可以据此记录日志或在测试中判断自己是否请求了重启。但何时真正执行重启，仍由 Gateway 网关控制。 -`api.runtime.config.loadConfig()` 和 `api.runtime.config.writeConfigFile(...)` 是已弃用的兼容辅助方法。它们会在运行时发出一次警告，内置插件不得使用它们；如果生产插件代码调用它们或从插件 SDK 子路径导入这些辅助方法，架构保护会失败。 +`api.runtime.config.loadConfig()` 和 `api.runtime.config.writeConfigFile(...)` 是已弃用的兼容性辅助函数。它们会在运行时警告一次，内置插件不得使用它们；如果生产插件代码调用这些函数，或从插件 SDK 子路径导入这些辅助函数，架构守卫就会失败。 -OpenClaw 内部运行时代码也遵循相同方向：在 CLI、Gateway 网关或进程边界处只加载一次配置，然后将该值一路传递下去。成功的变更写入会刷新进程运行时快照并推进其内部版本；长生命周期缓存应依赖运行时持有的缓存键，而不是在本地序列化配置。长生命周期运行时模块对环境式 `loadConfig()` 调用采用零容忍扫描；请使用传入的 `cfg`、请求级 `context.getRuntimeConfig()`，或在显式进程边界上使用 `getRuntimeConfig()`。 +OpenClaw 内部运行时代码也遵循相同方向：在 CLI、Gateway 网关或进程边界处加载一次配置，然后将该值一路传递下去。成功的变更写入会刷新进程运行时快照，并推进其内部修订版本；长生命周期缓存应基于运行时拥有的缓存键，而不是在本地序列化配置。长生命周期运行时模块对环境式 `loadConfig()` 调用采用零容忍扫描；请使用传入的 `cfg`、请求中的 `context.getRuntimeConfig()`，或在明确的进程边界处使用 `getRuntimeConfig()`。 ## 运行时命名空间 @@ -59,17 +59,28 @@ OpenClaw 内部运行时代码也遵循相同方向：在 CLI、Gateway 网关 智能体身份、目录和会话管理。 ```typescript - // 解析智能体工作目录 + // 解析智能体的工作目录 const agentDir = api.runtime.agent.resolveAgentDir(cfg); - // 解析智能体工作区 + // 解析 Agent 工作区 const workspaceDir = api.runtime.agent.resolveAgentWorkspaceDir(cfg); // 获取智能体身份 const identity = api.runtime.agent.resolveAgentIdentity(cfg); - // 获取默认思考级别 - const thinking = api.runtime.agent.resolveThinkingDefault(cfg, provider, model); + // 获取默认思考等级 + const thinking = api.runtime.agent.resolveThinkingDefault({ + cfg, + provider, + model, + }); + + // 根据当前提供商配置文件，校验用户提供的思考等级 + const policy = api.runtime.agent.resolveThinkingPolicy({ provider, model }); + const level = api.runtime.agent.normalizeThinkingLevel("extra high"); + if (level && policy.levels.some((entry) => entry.id === level)) { + // 将 level 传给嵌入式运行 + } // 获取智能体超时时间 const timeoutMs = api.runtime.agent.resolveAgentTimeoutMs(cfg); @@ -77,7 +88,7 @@ OpenClaw 内部运行时代码也遵循相同方向：在 CLI、Gateway 网关 // 确保工作区存在 await api.runtime.agent.ensureAgentWorkspace(cfg); - // 运行一个内置智能体轮次 + // 运行一次嵌入式智能体轮次 const agentDir = api.runtime.agent.resolveAgentDir(cfg); const result = await api.runtime.agent.runEmbeddedAgent({ sessionId: "my-plugin:task-1", @@ -89,11 +100,15 @@ OpenClaw 内部运行时代码也遵循相同方向：在 CLI、Gateway 网关 }); ``` - `runEmbeddedAgent(...)` 是从插件代码启动常规 OpenClaw 智能体轮次的中立辅助方法。它使用与渠道触发回复相同的 provider/模型解析和 agent-harness 选择逻辑。 + `runEmbeddedAgent(...)` 是一个中立的辅助函数，用于从插件代码中启动一次普通的 OpenClaw 智能体轮次。它使用与渠道触发回复相同的 provider / model 解析逻辑和智能体 harness 选择逻辑。 - `runEmbeddedPiAgent(...)` 仍保留为兼容别名。 + `runEmbeddedPiAgent(...)` 仍保留为兼容性别名。 - **会话存储辅助方法** 位于 `api.runtime.agent.session` 下： + `resolveThinkingPolicy(...)` 返回 provider / model 支持的思考等级以及可选的默认值。提供商插件通过其思考钩子拥有模型特定配置文件，因此工具插件应调用这个运行时辅助函数，而不是导入或复制提供商列表。 + + `normalizeThinkingLevel(...)` 会将用户文本（例如 `on`、`x-high` 或 `extra high`）转换为规范化的已存储等级，然后再根据已解析的策略进行检查。 + + **会话存储辅助函数** 位于 `api.runtime.agent.session` 下： ```typescript const storePath = api.runtime.agent.session.resolveStorePath(cfg); @@ -141,14 +156,14 @@ OpenClaw 内部运行时代码也遵循相同方向：在 CLI、Gateway 网关 ``` - 模型覆盖（`provider`/`model`）要求操作员通过配置中的 `plugins.entries..subagent.allowModelOverride: true` 显式启用。未受信任的插件仍可运行子智能体，但其覆盖请求会被拒绝。 + 模型覆盖（`provider` / `model`）需要操作员在配置中通过 `plugins.entries..subagent.allowModelOverride: true` 显式启用。不受信任的插件仍可运行子智能体，但覆盖请求会被拒绝。 - `deleteSession(...)` 可以删除由同一插件通过 `api.runtime.subagent.run(...)` 创建的会话。删除任意用户或操作员会话仍需要管理员范围的 Gateway 网关请求。 + `deleteSession(...)` 可以删除同一个插件通过 `api.runtime.subagent.run(...)` 创建的会话。删除任意用户或操作员会话，仍然需要管理员作用域的 Gateway 网关请求。 - 列出已连接节点，并从 Gateway 网关加载的插件代码或插件 CLI 命令中调用节点宿主命令。当插件在已配对设备上拥有本地工作时，请使用此功能，例如另一台 Mac 上的浏览器或音频桥接器。 + 列出已连接的节点，并从 Gateway 网关加载的插件代码或插件 CLI 命令中调用节点宿主命令。当插件在已配对设备上拥有本地工作时，请使用此功能，例如另一台 Mac 上的浏览器桥接或音频桥接。 ```typescript const { nodes } = await api.runtime.nodes.list({ connected: true }); @@ -161,11 +176,11 @@ OpenClaw 内部运行时代码也遵循相同方向：在 CLI、Gateway 网关 }); ``` - 在 Gateway 网关内部，这个运行时是进程内的。在插件 CLI 命令中，它会通过 RPC 调用已配置的 Gateway 网关，因此像 `openclaw googlemeet recover-tab` 这样的命令可以从终端检查已配对节点。节点命令仍然会经过常规的 Gateway 网关节点配对、命令允许列表和节点本地命令处理流程。 + 在 Gateway 网关内部，这个运行时在进程内工作。在插件 CLI 命令中，它会通过 RPC 调用已配置的 Gateway 网关，因此像 `openclaw googlemeet recover-tab` 这样的命令可以从终端检查已配对节点。节点命令仍会经过正常的 Gateway 网关节点配对、命令允许列表和节点本地命令处理流程。 - 将 Task Flow 运行时绑定到现有 OpenClaw 会话键或受信任工具上下文，然后在每次调用时都不必传递 owner，即可创建和管理 Task Flow。 + 将 Task Flow 运行时绑定到现有 OpenClaw 会话键或受信任的工具上下文，然后在每次调用时无需传递 owner 也能创建和管理 Task Flows。 ```typescript const taskFlow = api.runtime.taskFlow.fromToolContext(ctx); @@ -192,7 +207,7 @@ OpenClaw 内部运行时代码也遵循相同方向：在 CLI、Gateway 网关 }); ``` - 当你已经从自己的绑定层拿到一个受信任的 OpenClaw 会话键时，请使用 `bindSession({ sessionKey, requesterOrigin })`。不要从原始用户输入中进行绑定。 + 当你已经从自己的绑定层获得一个受信任的 OpenClaw 会话键时，请使用 `bindSession({ sessionKey, requesterOrigin })`。不要从原始用户输入中进行绑定。 @@ -211,14 +226,14 @@ OpenClaw 内部运行时代码也遵循相同方向：在 CLI、Gateway 网关 cfg: api.config, }); - // 列出可用声音 + // 列出可用音色 const voices = await api.runtime.tts.listVoices({ provider: "elevenlabs", cfg: api.config, }); ``` - 使用核心 `messages.tts` 配置和提供商选择。返回 PCM 音频缓冲区 + 采样率。 + 使用核心 `messages.tts` 配置和提供商选择。返回 PCM 音频缓冲区和采样率。 @@ -232,11 +247,11 @@ OpenClaw 内部运行时代码也遵循相同方向：在 CLI、Gateway 网关 agentDir: "/tmp/agent", }); - // 转写音频 + // 转录音频 const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({ filePath: "/tmp/inbound-audio.ogg", cfg: api.config, - mime: "audio/ogg", // 可选，用于无法推断 MIME 时 + mime: "audio/ogg", // 可选，用于无法推断 MIME 类型时 }); // 描述视频 @@ -252,10 +267,10 @@ OpenClaw 内部运行时代码也遵循相同方向：在 CLI、Gateway 网关 }); ``` - 当未产生输出时，会返回 `{ text: undefined }`（例如输入被跳过时）。 + 当没有生成输出时（例如输入被跳过），返回 `{ text: undefined }`。 - `api.runtime.stt.transcribeAudioFile(...)` 仍保留为 `api.runtime.mediaUnderstanding.transcribeAudioFile(...)` 的兼容别名。 + `api.runtime.stt.transcribeAudioFile(...)` 仍保留为 `api.runtime.mediaUnderstanding.transcribeAudioFile(...)` 的兼容性别名。 @@ -273,7 +288,7 @@ OpenClaw 内部运行时代码也遵循相同方向：在 CLI、Gateway 网关 - web 搜索。 + 网页搜索。 ```typescript const providers = api.runtime.webSearch.listProviders({ config: api.config }); @@ -311,7 +326,8 @@ OpenClaw 内部运行时代码也遵循相同方向：在 CLI、Gateway 网关 - 当前运行时配置快照和事务性配置写入。优先使用已传入当前调用路径的配置；仅在处理器需要直接访问进程快照时使用 `current()`。 + 当前运行时配置快照和事务性配置写入。优先使用已经传入当前调用路径的配置；仅当处理器需要直接访问进程快照时，才使用 + `current()`。 ```typescript const cfg = api.runtime.config.current(); @@ -324,8 +340,7 @@ OpenClaw 内部运行时代码也遵循相同方向：在 CLI、Gateway 网关 ``` `mutateConfigFile(...)` 和 `replaceConfigFile(...)` 会返回一个 `followUp` - 值，例如 `{ mode: "restart", requiresRestart: true, reason }`， - 用于记录写入方意图，同时又不会从 Gateway 网关手中夺走重启控制权。 + 值，例如 `{ mode: "restart", requiresRestart: true, reason }`，用于记录写入方的意图，同时不会从 Gateway 网关手中夺走重启控制权。 @@ -353,7 +368,7 @@ OpenClaw 内部运行时代码也遵循相同方向：在 CLI、Gateway 网关 - 日志。 + 日志记录。 ```typescript const verbose = api.runtime.logging.shouldLogVerbose(); @@ -362,7 +377,7 @@ OpenClaw 内部运行时代码也遵循相同方向：在 CLI、Gateway 网关 - 模型和提供商身份验证解析。 + 模型和提供商凭证解析。 ```typescript const auth = await api.runtime.modelAuth.getApiKeyForModel({ model, cfg }); @@ -382,7 +397,7 @@ OpenClaw 内部运行时代码也遵循相同方向：在 CLI、Gateway 网关 - memory 工具工厂和 CLI。 + Memory 工具工厂和 CLI。 ```typescript const getTool = api.runtime.tools.createMemoryGetTool(/* ... */); @@ -392,9 +407,9 @@ OpenClaw 内部运行时代码也遵循相同方向：在 CLI、Gateway 网关 - 渠道专用运行时辅助方法（在加载渠道插件时可用）。 + 渠道特定的运行时辅助函数（在加载渠道插件时可用）。 - `api.runtime.channel.mentions` 是供使用运行时注入的内置渠道插件共享的入站提及策略界面： + `api.runtime.channel.mentions` 是供使用运行时注入的内置渠道插件共享的入站提及策略接口： ```typescript const mentionMatch = api.runtime.channel.mentions.matchesMentionWithExplicit(text, { @@ -421,7 +436,7 @@ OpenClaw 内部运行时代码也遵循相同方向：在 CLI、Gateway 网关 }); ``` - 可用的提及辅助方法： + 可用的提及辅助函数： - `buildMentionRegexes` - `matchesMentionPatterns` @@ -429,14 +444,14 @@ OpenClaw 内部运行时代码也遵循相同方向：在 CLI、Gateway 网关 - `implicitMentionKindWhen` - `resolveInboundMentionDecision` - `api.runtime.channel.mentions` 有意不暴露旧版 `resolveMentionGating*` 兼容辅助方法。请优先使用规范化后的 `{ facts, policy }` 路径。 + `api.runtime.channel.mentions` 有意不暴露较旧的 `resolveMentionGating*` 兼容性辅助函数。请优先使用规范化的 `{ facts, policy }` 路径。 ## 存储运行时引用 -使用 `createPluginRuntimeStore` 存储运行时引用，以便在 `register` 回调之外使用： +使用 `createPluginRuntimeStore` 来存储运行时引用，以便在 `register` 回调之外使用： @@ -451,7 +466,7 @@ OpenClaw 内部运行时代码也遵循相同方向：在 CLI、Gateway 网关 ``` - + ```typescript export default defineChannelPluginEntry({ id: "my-plugin", @@ -465,11 +480,11 @@ OpenClaw 内部运行时代码也遵循相同方向：在 CLI、Gateway 网关 ```typescript export function getRuntime() { - return store.getRuntime(); // 未初始化时抛出错误 + return store.getRuntime(); // 如果尚未初始化则抛出异常 } export function tryGetRuntime() { - return store.tryGetRuntime(); // 未初始化时返回 null + return store.tryGetRuntime(); // 如果尚未初始化则返回 null } ``` @@ -477,7 +492,7 @@ OpenClaw 内部运行时代码也遵循相同方向：在 CLI、Gateway 网关 -对于 runtime-store 身份，优先使用 `pluginId`。较底层的 `key` 形式适用于少见情况，即某个插件有意需要多个运行时槽位。 +运行时存储的标识应优先使用 `pluginId`。更底层的 `key` 形式适用于少见场景：某个插件有意需要多个运行时槽位。 ## 其他顶层 `api` 字段 @@ -491,23 +506,23 @@ OpenClaw 内部运行时代码也遵循相同方向：在 CLI、Gateway 网关 插件显示名称。 - 当前配置快照（可用时为活动的内存运行时快照）。 + 当前配置快照（如果可用，则为当前处于活动状态的内存运行时快照）。 来自 `plugins.entries..config` 的插件专用配置。 - 带作用域的日志记录器（`debug`、`info`、`warn`、`error`）。 + 作用域日志记录器（`debug`、`info`、`warn`、`error`）。 - 当前加载模式；`"setup-runtime"` 是完整入口启动/设置之前的轻量预启动窗口。 + 当前加载模式；`"setup-runtime"` 是完整入口启动 / 设置之前的轻量级窗口。 解析相对于插件根目录的路径。 -## 相关 +## 相关内容 -- [插件内部机制](/zh-CN/plugins/architecture) —— 能力模型和注册表 -- [插件 SDK 入口点](/zh-CN/plugins/sdk-entrypoints) —— `definePluginEntry` 选项 -- [插件 SDK 概览](/zh-CN/plugins/sdk-overview) —— 子路径参考 +- [插件架构内部机制](/zh-CN/plugins/architecture) — 能力模型和注册表 +- [插件入口点](/zh-CN/plugins/sdk-entrypoints) — `definePluginEntry` 选项 +- [插件 SDK 概览](/zh-CN/plugins/sdk-overview) — 子路径参考 diff --git a/docs/zh-CN/plugins/sdk-subpaths.md b/docs/zh-CN/plugins/sdk-subpaths.md index 167fad0ce..a10f399e9 100644 --- a/docs/zh-CN/plugins/sdk-subpaths.md +++ b/docs/zh-CN/plugins/sdk-subpaths.md @@ -1,286 +1,287 @@ --- read_when: - 为插件导入选择合适的 plugin-sdk 子路径 - - 审计内置插件子路径和辅助接口 -summary: 插件 SDK 子路径目录：按领域分组说明各导入位于何处 + - 审计内置插件子路径和辅助接口 surface +summary: 插件 SDK 子路径目录：按领域分组，哪些导入位于何处 title: 插件 SDK 子路径 x-i18n: - generated_at: "2026-04-27T12:55:01Z" + generated_at: "2026-04-27T13:19:42Z" model: gpt-5.4 provider: openai - source_hash: 422e88943203df6f86d63d113fafeee487b420f795d4373619874ccf58edc0f4 + source_hash: f9ee632a2c33f09b30a0b8a9f266fd57d92f754c19edf9d486c5c1fe5b539365 source_path: plugins/sdk-subpaths.md workflow: 15 --- - 插件 SDK 通过 `openclaw/plugin-sdk/` 下的一组窄子路径暴露。本页按用途对常用子路径进行归类整理。完整的 200+ 子路径生成列表位于 `scripts/lib/plugin-sdk-entrypoints.json`；保留的内置插件辅助子路径也会出现在其中，但除非某个文档页面明确推广，否则它们都属于实现细节。 + 插件 SDK 通过 `openclaw/plugin-sdk/` 下的一组精简子路径对外暴露。 + 本页按用途对常用子路径进行归类整理。生成的完整列表包含 200 多个子路径，位于 `scripts/lib/plugin-sdk-entrypoints.json`；其中也包含为内置插件保留的辅助子路径，但除非某个文档页面明确将其作为公开能力介绍，否则它们都属于实现细节。 - 关于插件编写指南，请参见 [插件 SDK 概览](/zh-CN/plugins/sdk-overview)。 + 关于插件编写指南，请参阅 [插件 SDK 概览](/zh-CN/plugins/sdk-overview)。 ## 插件入口 - | 子路径 | 关键导出 | - | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ | - | `plugin-sdk/plugin-entry` | `definePluginEntry` | - | `plugin-sdk/core` | `defineChannelPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase`, `defineSetupPluginEntry`, `buildChannelConfigSchema` | - | `plugin-sdk/config-schema` | `OpenClawSchema` | - | `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | - | `plugin-sdk/migration` | 迁移 provider 条目辅助工具，例如 `createMigrationItem`、原因常量、条目状态标记、脱敏辅助工具和 `summarizeMigrationItems` | - | `plugin-sdk/migration-runtime` | 运行时迁移辅助工具，例如 `copyMigrationFileItem` 和 `writeMigrationReport` | + | 子路径 | 关键导出 | + | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- | + | `plugin-sdk/plugin-entry` | `definePluginEntry` | + | `plugin-sdk/core` | `defineChannelPluginEntry`、`createChatChannelPlugin`、`createChannelPluginBase`、`defineSetupPluginEntry`、`buildChannelConfigSchema` | + | `plugin-sdk/config-schema` | `OpenClawSchema` | + | `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | + | `plugin-sdk/migration` | 迁移提供商条目辅助函数，例如 `createMigrationItem`、原因常量、条目状态标记、脱敏辅助函数，以及 `summarizeMigrationItems` | + | `plugin-sdk/migration-runtime` | 运行时迁移辅助函数，例如 `copyMigrationFileItem` 和 `writeMigrationReport` | | 子路径 | 关键导出 | | --- | --- | - | `plugin-sdk/channel-core` | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` | - | `plugin-sdk/config-schema` | 根 `openclaw.json` Zod 模式导出（`OpenClawSchema`） | - | `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`，以及 `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` | - | `plugin-sdk/setup` | 共享设置向导辅助工具、allowlist 提示、设置状态构建器 | - | `plugin-sdk/setup-runtime` | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` | + | `plugin-sdk/channel-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`、account-id 规范化辅助工具 | - | `plugin-sdk/account-resolution` | 账户查找 + 默认回退辅助工具 | - | `plugin-sdk/account-helpers` | 窄范围账户列表/账户操作辅助工具 | + | `plugin-sdk/setup-tools` | `formatCliCommand`、`detectBinary`、`extractArchive`、`resolveBrewExecutable`、`formatDocsLink`、`CONFIG_DIR` | + | `plugin-sdk/account-core` | 多账户配置 / 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` | 共享渠道配置模式原语和通用构建器 | - | `plugin-sdk/channel-config-schema-legacy` | 已弃用的内置渠道配置模式，仅用于内置兼容性 | - | `plugin-sdk/telegram-command-config` | 带内置契约回退的 Telegram 自定义命令规范化/验证辅助工具 | - | `plugin-sdk/command-gating` | 窄范围命令授权门控辅助工具 | + | `plugin-sdk/channel-config-schema` | 共享渠道配置 schema 原语和通用构建器 | + | `plugin-sdk/channel-config-schema-legacy` | 已弃用的内置渠道配置 schema，仅用于保持内置兼容性 | + | `plugin-sdk/telegram-command-config` | Telegram 自定义命令规范化 / 校验辅助函数，并带有内置契约回退 | + | `plugin-sdk/command-gating` | 精简的命令授权门控辅助函数 | | `plugin-sdk/channel-policy` | `resolveChannelGroupRequireMention` | - | `plugin-sdk/channel-lifecycle` | `createAccountStatusSink`、草稿流生命周期/最终化辅助工具 | - | `plugin-sdk/inbound-envelope` | 共享入站路由 + 信封构建辅助工具 | - | `plugin-sdk/inbound-reply-dispatch` | 共享入站记录和分发辅助工具 | - | `plugin-sdk/messaging-targets` | 目标解析/匹配辅助工具 | - | `plugin-sdk/outbound-media` | 共享出站媒体加载辅助工具 | - | `plugin-sdk/outbound-send-deps` | 渠道适配器使用的轻量级出站发送依赖查找 | - | `plugin-sdk/outbound-runtime` | 出站投递、身份、发送委托、会话、格式化和载荷规划辅助工具 | - | `plugin-sdk/poll-runtime` | 窄范围投票规范化辅助工具 | - | `plugin-sdk/thread-bindings-runtime` | 线程绑定生命周期和适配器辅助工具 | + | `plugin-sdk/channel-lifecycle` | `createAccountStatusSink`、草稿流生命周期 / 完成辅助函数 | + | `plugin-sdk/inbound-envelope` | 共享入站路由 + envelope 构建辅助函数 | + | `plugin-sdk/inbound-reply-dispatch` | 共享入站记录与分发辅助函数 | + | `plugin-sdk/messaging-targets` | 目标解析 / 匹配辅助函数 | + | `plugin-sdk/outbound-media` | 共享出站媒体加载辅助函数 | + | `plugin-sdk/outbound-send-deps` | 用于渠道适配器的轻量级出站发送依赖查找 | + | `plugin-sdk/outbound-runtime` | 出站投递、身份、发送委托、会话、格式化和载荷规划辅助函数 | + | `plugin-sdk/poll-runtime` | 精简的投票规范化辅助函数 | + | `plugin-sdk/thread-bindings-runtime` | 线程绑定生命周期和适配器辅助函数 | | `plugin-sdk/agent-media-payload` | 旧版智能体媒体载荷构建器 | - | `plugin-sdk/conversation-runtime` | 对话/线程绑定、配对和已配置绑定辅助工具 | - | `plugin-sdk/runtime-config-snapshot` | 运行时配置快照辅助工具 | - | `plugin-sdk/runtime-group-policy` | 运行时群组策略解析辅助工具 | - | `plugin-sdk/channel-status` | 共享渠道状态快照/摘要辅助工具 | - | `plugin-sdk/channel-config-primitives` | 窄范围渠道配置模式原语 | - | `plugin-sdk/channel-config-writes` | 渠道配置写入授权辅助工具 | + | `plugin-sdk/conversation-runtime` | 对话 / 线程绑定、配对和已配置绑定辅助函数 | + | `plugin-sdk/runtime-config-snapshot` | 运行时配置快照辅助函数 | + | `plugin-sdk/runtime-group-policy` | 运行时群组策略解析辅助函数 | + | `plugin-sdk/channel-status` | 共享渠道 Status 快照 / 摘要辅助函数 | + | `plugin-sdk/channel-config-primitives` | 精简的渠道配置 schema 原语 | + | `plugin-sdk/channel-config-writes` | 渠道配置写入授权辅助函数 | | `plugin-sdk/channel-plugin-common` | 共享渠道插件前导导出 | - | `plugin-sdk/allowlist-config-edit` | allowlist 配置编辑/读取辅助工具 | - | `plugin-sdk/group-access` | 共享群组访问决策辅助工具 | - | `plugin-sdk/direct-dm` | 共享直接私信认证/防护辅助工具 | - | `plugin-sdk/interactive-runtime` | 语义化消息展示、投递和旧版交互式回复辅助工具。参见 [消息展示](/zh-CN/plugins/message-presentation) | - | `plugin-sdk/channel-inbound` | 入站去抖、提及匹配、提及策略辅助工具和信封辅助工具的兼容性 barrel | - | `plugin-sdk/channel-inbound-debounce` | 窄范围入站去抖辅助工具 | - | `plugin-sdk/channel-mention-gating` | 窄范围提及策略和提及文本辅助工具，不包含更广泛的入站运行时接口 | - | `plugin-sdk/channel-envelope` | 窄范围入站信封格式化辅助工具 | - | `plugin-sdk/channel-location` | 渠道位置上下文和格式化辅助工具 | - | `plugin-sdk/channel-logging` | 用于入站丢弃和 typing/ack 失败的渠道日志辅助工具 | + | `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-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` | 渠道消息操作辅助工具，以及为插件兼容性保留的已弃用原生模式辅助工具 | - | `plugin-sdk/channel-targets` | 目标解析/匹配辅助工具 | + | `plugin-sdk/channel-actions` | 渠道消息操作辅助函数，以及为插件兼容性保留的已弃用原生 schema 辅助函数 | + | `plugin-sdk/channel-targets` | 目标解析 / 匹配辅助函数 | | `plugin-sdk/channel-contract` | 渠道契约类型 | - | `plugin-sdk/channel-feedback` | 反馈/反应接线 | - | `plugin-sdk/channel-secret-runtime` | 窄范围秘密契约辅助工具，例如 `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment` 和秘密目标类型 | + | `plugin-sdk/channel-feedback` | 反馈 / reaction 连接 | + | `plugin-sdk/channel-secret-runtime` | 精简的密钥契约辅助函数，例如 `collectSimpleChannelFieldAssignments`、`getChannelSurface`、`pushAssignment` 和密钥目标类型 | | 子路径 | 关键导出 | | --- | --- | | `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | - | `plugin-sdk/lmstudio` | 用于设置、目录发现和运行时模型准备的受支持 LM Studio provider 门面 | - | `plugin-sdk/lmstudio-runtime` | 用于本地服务器默认值、模型发现、请求头和已加载模型辅助工具的受支持 LM Studio 运行时门面 | - | `plugin-sdk/provider-setup` | 精选的本地/自托管 provider 设置辅助工具 | - | `plugin-sdk/self-hosted-provider-setup` | 聚焦于 OpenAI 兼容自托管 provider 的设置辅助工具 | + | `plugin-sdk/lmstudio` | 受支持的 LM Studio 提供商外观层，用于设置、目录发现和运行时模型准备 | + | `plugin-sdk/lmstudio-runtime` | 受支持的 LM Studio 运行时外观层，用于本地服务器默认值、模型发现、请求头和已加载模型辅助函数 | + | `plugin-sdk/provider-setup` | 经过整理的本地 / 自托管提供商设置辅助函数 | + | `plugin-sdk/self-hosted-provider-setup` | 面向 OpenAI 兼容自托管提供商的聚焦设置辅助函数 | | `plugin-sdk/cli-backend` | CLI 后端默认值 + watchdog 常量 | - | `plugin-sdk/provider-auth-runtime` | provider 插件的运行时 API key 解析辅助工具 | - | `plugin-sdk/provider-auth-api-key` | API key 新手引导/配置档写入辅助工具，例如 `upsertApiKeyProfile` | - | `plugin-sdk/provider-auth-result` | 标准 OAuth 认证结果构建器 | - | `plugin-sdk/provider-auth-login` | provider 插件共享的交互式登录辅助工具 | - | `plugin-sdk/provider-env-vars` | provider 认证环境变量查找辅助工具 | - | `plugin-sdk/provider-auth` | `createProviderApiKeyAuthMethod`, `ensureApiKeyFromOptionEnvOrPrompt`, `upsertAuthProfile`, `upsertApiKeyProfile`, `writeOAuthCredentials` | - | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`、共享 replay-policy 构建器、provider 端点辅助工具，以及如 `normalizeNativeXaiModelId` 之类的 model-id 规范化辅助工具 | - | `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | - | `plugin-sdk/provider-http` | 通用 provider HTTP/端点能力辅助工具、provider HTTP 错误和音频转录 multipart form 辅助工具 | - | `plugin-sdk/provider-web-fetch-contract` | 窄范围 web-fetch 配置/选择契约辅助工具，例如 `enablePluginInConfig` 和 `WebFetchProviderPlugin` | - | `plugin-sdk/provider-web-fetch` | Web-fetch provider 注册/缓存辅助工具 | - | `plugin-sdk/provider-web-search-config-contract` | 适用于不需要插件启用接线的 provider 的窄范围 web-search 配置/凭证辅助工具 | - | `plugin-sdk/provider-web-search-contract` | 窄范围 web-search 配置/凭证契约辅助工具，例如 `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` 以及作用域化凭证 setter/getter | - | `plugin-sdk/provider-web-search` | Web 搜索 provider 注册/缓存/运行时辅助工具 | - | `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, Gemini 模式清理 + 诊断，以及 xAI 兼容辅助工具，例如 `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | - | `plugin-sdk/provider-usage` | `fetchClaudeUsage` 等 | - | `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`、流包装器类型，以及共享的 Anthropic/Bedrock/DeepSeek V4/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot 包装器辅助工具 | - | `plugin-sdk/provider-transport-runtime` | 原生 provider 传输辅助工具，例如受保护 fetch、传输消息转换和可写传输事件流 | - | `plugin-sdk/provider-onboard` | 新手引导配置补丁辅助工具 | - | `plugin-sdk/global-singleton` | 进程本地 singleton/map/cache 辅助工具 | - | `plugin-sdk/group-activation` | 窄范围群组激活模式和命令解析辅助工具 | + | `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 构建器、提供商端点辅助函数，以及如 `normalizeNativeXaiModelId` 这样的 model-id 规范化辅助函数 | + | `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`、`buildSingleProviderApiKeyCatalog`、`supportsNativeStreamingUsageCompat`、`applyProviderNativeStreamingUsageCompat` | + | `plugin-sdk/provider-http` | 通用提供商 HTTP / 端点能力辅助函数、提供商 HTTP 错误，以及音频转录 multipart form 辅助函数 | + | `plugin-sdk/provider-web-fetch-contract` | 精简的 web-fetch 配置 / 选择契约辅助函数，例如 `enablePluginInConfig` 和 `WebFetchProviderPlugin` | + | `plugin-sdk/provider-web-fetch` | web-fetch 提供商注册 / 缓存辅助函数 | + | `plugin-sdk/provider-web-search-config-contract` | 面向不需要插件启用连接逻辑的提供商的精简 web-search 配置 / 凭证辅助函数 | + | `plugin-sdk/provider-web-search-contract` | 精简的 web-search 配置 / 凭证契约辅助函数，例如 `createWebSearchProviderContractFields`、`enablePluginInConfig`、`resolveProviderWebSearchPluginConfig`，以及作用域化凭证 setter / getter | + | `plugin-sdk/provider-web-search` | web-search 提供商注册 / 缓存 / 运行时辅助函数 | + | `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`、`buildProviderToolCompatFamilyHooks`、Gemini schema 清理 + 诊断，以及 xAI 兼容辅助函数，例如 `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | + | `plugin-sdk/provider-usage` | `fetchClaudeUsage` 及类似函数 | + | `plugin-sdk/provider-stream` | `ProviderStreamFamily`、`buildProviderStreamFamilyHooks`、`composeProviderStreamWrappers`、流包装器类型，以及共享的 Anthropic / Bedrock / DeepSeek V4 / Google / Kilocode / Moonshot / OpenAI / OpenRouter / Z.A.I / MiniMax / Copilot 包装器辅助函数 | + | `plugin-sdk/provider-transport-runtime` | 原生提供商传输辅助函数，例如受保护的 fetch、传输消息转换和可写传输事件流 | + | `plugin-sdk/provider-onboard` | 新手引导配置补丁辅助函数 | + | `plugin-sdk/global-singleton` | 进程本地 singleton / map / cache 辅助函数 | + | `plugin-sdk/group-activation` | 精简的群组激活模式和命令解析辅助函数 | - + | 子路径 | 关键导出 | | --- | --- | - | `plugin-sdk/command-auth` | `resolveControlCommandGate`、命令注册表辅助工具（包括动态参数菜单格式化）、发送者授权辅助工具 | - | `plugin-sdk/command-status` | 命令/帮助消息构建器，例如 `buildCommandsMessagePaginated` 和 `buildHelpMessage` | - | `plugin-sdk/approval-auth-runtime` | approver 解析和同聊天操作认证辅助工具 | - | `plugin-sdk/approval-client-runtime` | 原生 exec 审批配置档/过滤辅助工具 | - | `plugin-sdk/approval-delivery-runtime` | 原生审批能力/投递适配器 | - | `plugin-sdk/approval-gateway-runtime` | 共享审批 Gateway 网关解析辅助工具 | - | `plugin-sdk/approval-handler-adapter-runtime` | 用于热渠道入口点的轻量级原生审批适配器加载辅助工具 | - | `plugin-sdk/approval-handler-runtime` | 更广泛的审批处理器运行时辅助工具；如果更窄的 adapter/gateway 接缝已足够，优先使用那些 | - | `plugin-sdk/approval-native-runtime` | 原生审批目标 + 账户绑定辅助工具 | - | `plugin-sdk/approval-reply-runtime` | Exec/插件审批回复载荷辅助工具 | - | `plugin-sdk/approval-runtime` | Exec/插件审批载荷辅助工具、原生审批路由/运行时辅助工具，以及诸如 `formatApprovalDisplayPath` 之类的结构化审批显示辅助工具 | - | `plugin-sdk/reply-dedupe` | 窄范围入站回复去重重置辅助工具 | - | `plugin-sdk/channel-contract-testing` | 不含广泛 Testing barrel 的窄范围渠道契约测试辅助工具 | - | `plugin-sdk/command-auth-native` | 原生命令认证、动态参数菜单格式化和原生会话目标辅助工具 | - | `plugin-sdk/command-detection` | 共享命令检测辅助工具 | - | `plugin-sdk/command-primitives-runtime` | 用于热渠道路径的轻量级命令文本谓词 | - | `plugin-sdk/command-surface` | 命令主体规范化和命令表面辅助工具 | + | `plugin-sdk/command-auth` | `resolveControlCommandGate`、命令注册表辅助函数（包括动态参数菜单格式化）、发送者授权辅助函数 | + | `plugin-sdk/command-status` | 命令 / 帮助消息构建器，例如 `buildCommandsMessagePaginated` 和 `buildHelpMessage` | + | `plugin-sdk/approval-auth-runtime` | 审批人解析和同一聊天 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/approval-runtime` | exec / 插件审批载荷辅助函数、原生审批路由 / 运行时辅助函数，以及结构化审批显示辅助函数，例如 `formatApprovalDisplayPath` | + | `plugin-sdk/reply-dedupe` | 精简的入站回复去重重置辅助函数 | + | `plugin-sdk/channel-contract-testing` | 精简的渠道契约测试辅助函数，不包含宽泛的测试 barrel | + | `plugin-sdk/command-auth-native` | 原生命令认证、动态参数菜单格式化，以及原生会话目标辅助函数 | + | `plugin-sdk/command-detection` | 共享命令检测辅助函数 | + | `plugin-sdk/command-primitives-runtime` | 面向高频渠道路径的轻量级命令文本谓词 | + | `plugin-sdk/command-surface` | 命令正文规范化和命令接口辅助函数 | | `plugin-sdk/allow-from` | `formatAllowFromLowercase` | - | `plugin-sdk/channel-secret-runtime` | 用于渠道/插件秘密表面的窄范围秘密契约收集辅助工具 | - | `plugin-sdk/secret-ref-runtime` | 用于秘密契约/配置解析的窄范围 `coerceSecretRef` 和 SecretRef 类型辅助工具 | - | `plugin-sdk/security-runtime` | 共享信任、私信门控、外部内容、常量时间秘密比较和秘密收集辅助工具 | - | `plugin-sdk/ssrf-policy` | 主机 allowlist 和私有网络 SSRF 策略辅助工具 | - | `plugin-sdk/ssrf-dispatcher` | 不含广泛基础设施运行时接口的窄范围 pinned-dispatcher 辅助工具 | - | `plugin-sdk/ssrf-runtime` | pinned-dispatcher、带 SSRF 防护的 fetch、SSRF 错误和 SSRF 策略辅助工具 | - | `plugin-sdk/secret-input` | 秘密输入解析辅助工具 | - | `plugin-sdk/webhook-ingress` | Webhook 请求/目标辅助工具，以及原始 websocket/body 强制转换 | - | `plugin-sdk/webhook-request-guards` | 请求体大小/超时辅助工具 | + | `plugin-sdk/channel-secret-runtime` | 面向渠道 / 插件密钥接口的精简密钥契约收集辅助函数 | + | `plugin-sdk/secret-ref-runtime` | 面向密钥契约 / 配置解析的精简 `coerceSecretRef` 和 SecretRef 类型辅助函数 | + | `plugin-sdk/security-runtime` | 共享信任、私信门控、外部内容、敏感文本脱敏、常量时间密钥比较和密钥收集辅助函数 | + | `plugin-sdk/ssrf-policy` | 主机 allowlist 和私有网络 SSRF 策略辅助函数 | + | `plugin-sdk/ssrf-dispatcher` | 精简的 pinned-dispatcher 辅助函数，不包含宽泛的基础设施运行时接口 | + | `plugin-sdk/ssrf-runtime` | pinned-dispatcher、带 SSRF 防护的 fetch、SSRF 错误和 SSRF 策略辅助函数 | + | `plugin-sdk/secret-input` | 密钥输入解析辅助函数 | + | `plugin-sdk/webhook-ingress` | Webhook 请求 / 目标辅助函数，以及原始 websocket / body 强制转换 | + | `plugin-sdk/webhook-request-guards` | 请求体大小 / 超时辅助函数 | - + | 子路径 | 关键导出 | | --- | --- | - | `plugin-sdk/runtime` | 广泛的运行时/日志/备份/插件安装辅助工具 | - | `plugin-sdk/runtime-env` | 窄范围运行时环境、logger、超时、重试和退避辅助工具 | - | `plugin-sdk/browser-config` | 受支持的浏览器配置门面，用于规范化配置档/默认值、CDP URL 解析和浏览器控制认证辅助工具 | - | `plugin-sdk/channel-runtime-context` | 通用渠道运行时上下文注册和查找辅助工具 | + | `plugin-sdk/runtime` | 范围较广的运行时 / 日志 / 备份 / 插件安装辅助函数 | + | `plugin-sdk/runtime-env` | 精简的运行时环境、logger、超时、重试和退避辅助函数 | + | `plugin-sdk/browser-config` | 受支持的浏览器配置外观层，用于规范化 profile / 默认值、CDP URL 解析和浏览器控制认证辅助函数 | + | `plugin-sdk/channel-runtime-context` | 通用渠道运行时上下文注册和查找辅助函数 | | `plugin-sdk/runtime-store` | `createPluginRuntimeStore` | - | `plugin-sdk/plugin-runtime` | 共享插件命令/钩子/http/交互式辅助工具 | - | `plugin-sdk/hook-runtime` | 共享 webhook/内部钩子流水线辅助工具 | - | `plugin-sdk/lazy-runtime` | 延迟运行时导入/绑定辅助工具，例如 `createLazyRuntimeModule`、`createLazyRuntimeMethod` 和 `createLazyRuntimeSurface` | - | `plugin-sdk/process-runtime` | 进程 exec 辅助工具 | - | `plugin-sdk/cli-runtime` | CLI 格式化、等待、版本、参数调用和延迟命令组辅助工具 | - | `plugin-sdk/gateway-runtime` | Gateway 网关客户端、Gateway 网关 CLI RPC、Gateway 网关协议错误和渠道状态补丁辅助工具 | - | `plugin-sdk/config-runtime` | 配置加载/写入辅助工具和插件配置查找辅助工具 | - | `plugin-sdk/telegram-command-config` | Telegram 命令名称/描述规范化以及重复/冲突检查，即使内置 Telegram 契约表面不可用时也可使用 | - | `plugin-sdk/text-autolink-runtime` | 不含广泛文本运行时 barrel 的文件引用自动链接检测 | - | `plugin-sdk/approval-runtime` | Exec/插件审批辅助工具、审批能力构建器、认证/配置档辅助工具、原生路由/运行时辅助工具，以及结构化审批显示路径格式化 | - | `plugin-sdk/reply-runtime` | 共享入站/回复运行时辅助工具、分块、分发、heartbeat、回复规划器 | - | `plugin-sdk/reply-dispatch-runtime` | 窄范围回复分发/最终化和对话标签辅助工具 | - | `plugin-sdk/reply-history` | 共享短窗口回复历史辅助工具，例如 `buildHistoryContext`、`recordPendingHistoryEntry` 和 `clearHistoryEntriesIfEnabled` | + | `plugin-sdk/plugin-runtime` | 共享插件命令 / hook / http / 交互辅助函数 | + | `plugin-sdk/hook-runtime` | 共享 webhook / 内部钩子流水线辅助函数 | + | `plugin-sdk/lazy-runtime` | 惰性运行时导入 / 绑定辅助函数，例如 `createLazyRuntimeModule`、`createLazyRuntimeMethod` 和 `createLazyRuntimeSurface` | + | `plugin-sdk/process-runtime` | 进程 exec 辅助函数 | + | `plugin-sdk/cli-runtime` | CLI 格式化、等待、版本、参数调用和惰性命令组辅助函数 | + | `plugin-sdk/gateway-runtime` | Gateway 网关客户端、Gateway 网关 CLI RPC、Gateway 网关协议错误以及渠道 Status 补丁辅助函数 | + | `plugin-sdk/config-runtime` | 配置加载 / 写入辅助函数，以及插件配置查找辅助函数 | + | `plugin-sdk/telegram-command-config` | Telegram 命令名称 / 描述规范化以及重复 / 冲突检查，即使内置 Telegram 契约接口不可用时也可使用 | + | `plugin-sdk/text-autolink-runtime` | 文件引用自动链接检测，不包含宽泛的 text-runtime barrel | + | `plugin-sdk/approval-runtime` | exec / 插件审批辅助函数、审批能力构建器、认证 / profile 辅助函数、原生路由 / 运行时辅助函数，以及结构化审批显示路径格式化 | + | `plugin-sdk/reply-runtime` | 共享入站 / 回复运行时辅助函数、分块、分发、心跳、回复规划器 | + | `plugin-sdk/reply-dispatch-runtime` | 精简的回复分发 / 完成以及对话标签辅助函数 | + | `plugin-sdk/reply-history` | 共享短窗口回复历史辅助函数，例如 `buildHistoryContext`、`recordPendingHistoryEntry` 和 `clearHistoryEntriesIfEnabled` | | `plugin-sdk/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/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` | 共享渠道 / 账户 Status 摘要辅助函数、运行时状态默认值和问题元数据辅助函数 | + | `plugin-sdk/target-resolver-runtime` | 共享目标解析器辅助函数 | + | `plugin-sdk/string-normalization-runtime` | slug / 字符串规范化辅助函数 | + | `plugin-sdk/request-url` | 从 fetch / 类 request 输入中提取字符串 URL | + | `plugin-sdk/run-command` | 带超时控制的命令运行器，返回已规范化的 stdout / stderr 结果 | + | `plugin-sdk/param-readers` | 通用工具 / CLI 参数读取器 | | `plugin-sdk/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` | 窄范围智能体运行时配置模式原语 | + | `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` | 精简的 Agent Runtimes 配置 schema 原语 | | `plugin-sdk/boolean-param` | 宽松布尔参数读取器 | - | `plugin-sdk/dangerous-name-runtime` | 危险名称匹配解析辅助工具 | - | `plugin-sdk/device-bootstrap` | 设备引导和配对令牌辅助工具 | - | `plugin-sdk/extension-shared` | 共享被动渠道、状态和环境代理辅助原语 | - | `plugin-sdk/models-provider-runtime` | `/models` 命令/provider 回复辅助工具 | - | `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 端点检测辅助工具 | - | `plugin-sdk/infra-runtime` | 系统事件/heartbeat 辅助工具 | - | `plugin-sdk/collection-runtime` | 小型有界缓存辅助工具 | - | `plugin-sdk/diagnostic-runtime` | 诊断标志和事件辅助工具 | - | `plugin-sdk/error-runtime` | 错误图、格式化、共享错误分类辅助工具、`isApprovalNotFoundError` | - | `plugin-sdk/fetch-runtime` | 封装的 fetch、代理和 pinned 查找辅助工具 | - | `plugin-sdk/runtime-fetch` | 不含代理/guarded-fetch 导入的 dispatcher 感知运行时 fetch | - | `plugin-sdk/response-limit-runtime` | 不含广泛媒体运行时表面的有界响应体读取器 | - | `plugin-sdk/session-binding-runtime` | 当前对话绑定状态，不含已配置绑定路由或配对存储 | - | `plugin-sdk/session-store-runtime` | 不含广泛配置写入/维护导入的会话存储读取辅助工具 | - | `plugin-sdk/context-visibility-runtime` | 上下文可见性解析和补充上下文过滤，不含广泛配置/安全导入 | - | `plugin-sdk/string-coerce-runtime` | 不含 Markdown/日志导入的窄范围原始记录/字符串强制转换和规范化辅助工具 | - | `plugin-sdk/host-runtime` | 主机名和 SCP 主机规范化辅助工具 | - | `plugin-sdk/retry-runtime` | 重试配置和重试运行器辅助工具 | - | `plugin-sdk/agent-runtime` | 智能体目录/身份/工作区辅助工具 | - | `plugin-sdk/directory-runtime` | 配置支持的目录查询/去重 | + | `plugin-sdk/dangerous-name-runtime` | 危险名称匹配解析辅助函数 | + | `plugin-sdk/device-bootstrap` | 设备引导和配对令牌辅助函数 | + | `plugin-sdk/extension-shared` | 共享被动渠道、Status 和环境代理辅助原语 | + | `plugin-sdk/models-provider-runtime` | `/models` 命令 / 提供商回复辅助函数 | + | `plugin-sdk/skill-commands-runtime` | Skills 命令列表辅助函数 | + | `plugin-sdk/native-command-registry` | 原生命令注册表构建 / 序列化辅助函数 | + | `plugin-sdk/agent-harness` | 面向受信任插件的实验性低层 Agent harness 接口：harness 类型、活动运行 steer / abort 辅助函数、OpenClaw 工具桥接辅助函数、运行时规划工具策略辅助函数、终端结果分类、工具进度格式化 / 细节辅助函数，以及尝试结果工具函数 | + | `plugin-sdk/provider-zai-endpoint` | Z.A.I 端点检测辅助函数 | + | `plugin-sdk/infra-runtime` | 系统事件 / 心跳辅助函数 | + | `plugin-sdk/collection-runtime` | 小型有界缓存辅助函数 | + | `plugin-sdk/diagnostic-runtime` | 诊断标志、事件和 trace-context 辅助函数 | + | `plugin-sdk/error-runtime` | 错误图、格式化、共享错误分类辅助函数、`isApprovalNotFoundError` | + | `plugin-sdk/fetch-runtime` | 封装后的 fetch、代理和固定查找辅助函数 | + | `plugin-sdk/runtime-fetch` | 感知 dispatcher 的运行时 fetch，不引入代理 / 受保护 fetch 导入 | + | `plugin-sdk/response-limit-runtime` | 有界响应体读取器，不包含宽泛的媒体运行时接口 | + | `plugin-sdk/session-binding-runtime` | 当前对话绑定状态，不包含已配置绑定路由或配对存储 | + | `plugin-sdk/session-store-runtime` | 会话存储读取辅助函数，不引入宽泛的配置写入 / 维护导入 | + | `plugin-sdk/context-visibility-runtime` | 上下文可见性解析和补充上下文过滤，不引入宽泛的配置 / 安全导入 | + | `plugin-sdk/string-coerce-runtime` | 精简的原始记录 / 字符串强制转换和规范化辅助函数，不引入 markdown / 日志导入 | + | `plugin-sdk/host-runtime` | 主机名和 SCP 主机规范化辅助函数 | + | `plugin-sdk/retry-runtime` | 重试配置和重试执行器辅助函数 | + | `plugin-sdk/agent-runtime` | 智能体目录 / 身份 / 工作区辅助函数 | + | `plugin-sdk/directory-runtime` | 基于配置的目录查询 / 去重 | | `plugin-sdk/keyed-async-queue` | `KeyedAsyncQueue` | - + | 子路径 | 关键导出 | | --- | --- | - | `plugin-sdk/media-runtime` | 共享媒体获取/转换/存储辅助工具，以及媒体载荷构建器 | - | `plugin-sdk/media-store` | 窄范围媒体存储辅助工具，例如 `saveMediaBuffer` | - | `plugin-sdk/media-generation-runtime` | 共享媒体生成故障切换辅助工具、候选项选择和缺失模型提示 | - | `plugin-sdk/media-understanding` | 媒体理解 provider 类型，以及面向 provider 的图像/音频辅助导出 | - | `plugin-sdk/text-runtime` | 共享文本/Markdown/日志辅助工具，例如面向助手可见文本剥离、Markdown 渲染/分块/表格辅助工具、脱敏辅助工具、指令标签辅助工具和安全文本工具函数 | - | `plugin-sdk/text-chunking` | 出站文本分块辅助工具 | - | `plugin-sdk/speech` | 语音 provider 类型，以及面向 provider 的指令、注册表、验证和语音辅助导出 | - | `plugin-sdk/speech-core` | 共享语音 provider 类型、注册表、指令、规范化和语音辅助导出 | - | `plugin-sdk/realtime-transcription` | 实时转录 provider 类型、注册表辅助工具和共享 WebSocket 会话辅助工具 | - | `plugin-sdk/realtime-voice` | 实时语音 provider 类型和注册表辅助工具 | - | `plugin-sdk/image-generation` | 图像生成 provider 类型 | - | `plugin-sdk/image-generation-core` | 共享图像生成类型、故障切换、认证和注册表辅助工具 | - | `plugin-sdk/music-generation` | 音乐生成 provider/请求/结果类型 | - | `plugin-sdk/music-generation-core` | 共享音乐生成类型、故障切换辅助工具、provider 查找和 model-ref 解析 | - | `plugin-sdk/video-generation` | 视频生成 provider/请求/结果类型 | - | `plugin-sdk/video-generation-core` | 共享视频生成类型、故障切换辅助工具、provider 查找和 model-ref 解析 | - | `plugin-sdk/webhook-targets` | Webhook 目标注册表和路由安装辅助工具 | - | `plugin-sdk/webhook-path` | Webhook 路径规范化辅助工具 | - | `plugin-sdk/web-media` | 共享远程/本地媒体加载辅助工具 | + | `plugin-sdk/media-runtime` | 共享媒体获取 / 转换 / 存储辅助函数，以及媒体载荷构建器 | + | `plugin-sdk/media-store` | 精简的媒体存储辅助函数，例如 `saveMediaBuffer` | + | `plugin-sdk/media-generation-runtime` | 共享媒体生成故障转移辅助函数、候选项选择和缺失模型提示 | + | `plugin-sdk/media-understanding` | 媒体理解提供商类型，以及面向提供商的图像 / 音频辅助导出 | + | `plugin-sdk/text-runtime` | 共享文本 / Markdown / 日志辅助函数，例如去除对助手可见文本、Markdown 渲染 / 分块 / 表格辅助函数、脱敏辅助函数、directive-tag 辅助函数和安全文本工具 | + | `plugin-sdk/text-chunking` | 出站文本分块辅助函数 | + | `plugin-sdk/speech` | Speech 提供商类型，以及面向提供商的 directive、注册表、校验和 speech 辅助导出 | + | `plugin-sdk/speech-core` | 共享 Speech 提供商类型、注册表、directive、规范化和 speech 辅助导出 | + | `plugin-sdk/realtime-transcription` | 实时转录提供商类型、注册表辅助函数和共享 WebSocket 会话辅助函数 | + | `plugin-sdk/realtime-voice` | 实时语音提供商类型和注册表辅助函数 | + | `plugin-sdk/image-generation` | 图像生成提供商类型 | + | `plugin-sdk/image-generation-core` | 共享图像生成类型、故障转移、认证和注册表辅助函数 | + | `plugin-sdk/music-generation` | 音乐生成提供商 / 请求 / 结果类型 | + | `plugin-sdk/music-generation-core` | 共享音乐生成类型、故障转移辅助函数、提供商查找和 model-ref 解析 | + | `plugin-sdk/video-generation` | 视频生成提供商 / 请求 / 结果类型 | + | `plugin-sdk/video-generation-core` | 共享视频生成类型、故障转移辅助函数、提供商查找和 model-ref 解析 | + | `plugin-sdk/webhook-targets` | Webhook 目标注册表和路由安装辅助函数 | + | `plugin-sdk/webhook-path` | Webhook 路径规范化辅助函数 | + | `plugin-sdk/web-media` | 共享远程 / 本地媒体加载辅助函数 | | `plugin-sdk/zod` | 为插件 SDK 使用者重新导出的 `zod` | - | `plugin-sdk/testing` | `installCommonResolveTargetErrorCases`, `shouldAckReaction` | + | `plugin-sdk/testing` | `installCommonResolveTargetErrorCases`、`shouldAckReaction` | | 子路径 | 关键导出 | | --- | --- | - | `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 契约、注册表访问、本地 provider 以及通用批处理/远程辅助工具 | - | `plugin-sdk/memory-core-host-engine-qmd` | Memory host QMD 引擎导出 | - | `plugin-sdk/memory-core-host-engine-storage` | Memory host 存储引擎导出 | - | `plugin-sdk/memory-core-host-multimodal` | Memory host 多模态辅助工具 | - | `plugin-sdk/memory-core-host-query` | Memory host 查询辅助工具 | - | `plugin-sdk/memory-core-host-secret` | Memory host 秘密辅助工具 | - | `plugin-sdk/memory-core-host-events` | Memory host 事件日志辅助工具 | - | `plugin-sdk/memory-core-host-status` | Memory host 状态辅助工具 | - | `plugin-sdk/memory-core-host-runtime-cli` | Memory host CLI 运行时辅助工具 | - | `plugin-sdk/memory-core-host-runtime-core` | Memory host 核心运行时辅助工具 | - | `plugin-sdk/memory-core-host-runtime-files` | Memory host 文件/运行时辅助工具 | - | `plugin-sdk/memory-host-core` | 面向 vendor 中立的 Memory host 核心运行时辅助工具别名 | - | `plugin-sdk/memory-host-events` | 面向 vendor 中立的 Memory host 事件日志辅助工具别名 | - | `plugin-sdk/memory-host-files` | 面向 vendor 中立的 Memory host 文件/运行时辅助工具别名 | - | `plugin-sdk/memory-host-markdown` | 用于 Memory 相邻插件的共享托管 Markdown 辅助工具 | - | `plugin-sdk/memory-host-search` | 用于 search-manager 访问的活动 Memory 运行时门面 | - | `plugin-sdk/memory-host-status` | 面向 vendor 中立的 Memory host 状态辅助工具别名 | - | `plugin-sdk/memory-lancedb` | 内置的 memory-lancedb 辅助接口 | + | `plugin-sdk/memory-core` | 内置 memory-core 辅助接口，用于 manager / 配置 / 文件 / CLI 辅助函数 | + | `plugin-sdk/memory-core-engine-runtime` | Memory 索引 / 搜索运行时外观层 | + | `plugin-sdk/memory-core-host-engine-foundation` | Memory 主机 foundation 引擎导出 | + | `plugin-sdk/memory-core-host-engine-embeddings` | Memory 主机 embedding 契约、注册表访问、本地提供商，以及通用批处理 / 远程辅助函数 | + | `plugin-sdk/memory-core-host-engine-qmd` | Memory 主机 QMD 引擎导出 | + | `plugin-sdk/memory-core-host-engine-storage` | Memory 主机存储引擎导出 | + | `plugin-sdk/memory-core-host-multimodal` | Memory 主机多模态辅助函数 | + | `plugin-sdk/memory-core-host-query` | Memory 主机查询辅助函数 | + | `plugin-sdk/memory-core-host-secret` | Memory 主机密钥辅助函数 | + | `plugin-sdk/memory-core-host-events` | Memory 主机事件日志辅助函数 | + | `plugin-sdk/memory-core-host-status` | Memory 主机 Status 辅助函数 | + | `plugin-sdk/memory-core-host-runtime-cli` | Memory 主机 CLI 运行时辅助函数 | + | `plugin-sdk/memory-core-host-runtime-core` | Memory 主机核心运行时辅助函数 | + | `plugin-sdk/memory-core-host-runtime-files` | Memory 主机文件 / 运行时辅助函数 | + | `plugin-sdk/memory-host-core` | 面向供应商中立的 memory 主机核心运行时辅助函数别名 | + | `plugin-sdk/memory-host-events` | 面向供应商中立的 memory 主机事件日志辅助函数别名 | + | `plugin-sdk/memory-host-files` | 面向供应商中立的 memory 主机文件 / 运行时辅助函数别名 | + | `plugin-sdk/memory-host-markdown` | 面向 memory 邻接插件的共享托管 Markdown 辅助函数 | + | `plugin-sdk/memory-host-search` | 用于访问 search-manager 的活动 Memory 运行时外观层 | + | `plugin-sdk/memory-host-status` | 面向供应商中立的 memory 主机 Status 辅助函数别名 | + | `plugin-sdk/memory-lancedb` | 内置 memory-lancedb 辅助接口 | | 家族 | 当前子路径 | 预期用途 | | --- | --- | --- | - | 浏览器 | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | 内置浏览器插件支持辅助工具。`browser-profiles` 导出 `resolveBrowserConfig`、`resolveProfile`、`ResolvedBrowserConfig`、`ResolvedBrowserProfile` 和 `ResolvedBrowserTabCleanupConfig`，用于规范化后的 `browser.tabCleanup` 结构。`browser-support` 仍然是兼容性 barrel。 | - | Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | 内置 Matrix 辅助/运行时接口 | - | Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | 内置 LINE 辅助/运行时接口 | - | IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | 内置 IRC 辅助接口 | - | 渠道特定辅助工具 | `plugin-sdk/googlechat`, `plugin-sdk/googlechat-runtime-shared`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu`, `plugin-sdk/feishu-conversation`, `plugin-sdk/feishu-setup`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/telegram-command-ui`, `plugin-sdk/tlon`, `plugin-sdk/twitch`, `plugin-sdk/zalo`, `plugin-sdk/zalo-setup` | 已弃用的内置渠道兼容/辅助接缝。新插件应导入通用 SDK 子路径或插件本地 barrel。 | - | 认证/插件特定辅助工具 | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diagnostics-prometheus`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/memory-core`, `plugin-sdk/memory-lancedb`, `plugin-sdk/opencode`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | 内置功能/插件辅助接缝；`plugin-sdk/github-copilot-token` 当前导出 `DEFAULT_COPILOT_API_BASE_URL`、`deriveCopilotApiBaseUrlFromToken` 和 `resolveCopilotApiToken` | + | Browser | `plugin-sdk/browser-cdp`、`plugin-sdk/browser-config-runtime`、`plugin-sdk/browser-config-support`、`plugin-sdk/browser-control-auth`、`plugin-sdk/browser-node-runtime`、`plugin-sdk/browser-profiles`、`plugin-sdk/browser-security-runtime`、`plugin-sdk/browser-setup-tools`、`plugin-sdk/browser-support` | 内置浏览器插件支持辅助函数。`browser-profiles` 导出 `resolveBrowserConfig`、`resolveProfile`、`ResolvedBrowserConfig`、`ResolvedBrowserProfile` 和 `ResolvedBrowserTabCleanupConfig`，用于规范化后的 `browser.tabCleanup` 结构。`browser-support` 仍然是兼容性 barrel。 | + | Matrix | `plugin-sdk/matrix`、`plugin-sdk/matrix-helper`、`plugin-sdk/matrix-runtime-heavy`、`plugin-sdk/matrix-runtime-shared`、`plugin-sdk/matrix-runtime-surface`、`plugin-sdk/matrix-surface`、`plugin-sdk/matrix-thread-bindings` | 内置 Matrix 辅助 / 运行时接口 | + | Line | `plugin-sdk/line`、`plugin-sdk/line-core`、`plugin-sdk/line-runtime`、`plugin-sdk/line-surface` | 内置 LINE 辅助 / 运行时接口 | + | IRC | `plugin-sdk/irc`、`plugin-sdk/irc-surface` | 内置 IRC 辅助接口 | + | 渠道专用辅助函数 | `plugin-sdk/googlechat`、`plugin-sdk/googlechat-runtime-shared`、`plugin-sdk/zalouser`、`plugin-sdk/bluebubbles`、`plugin-sdk/bluebubbles-policy`、`plugin-sdk/mattermost`、`plugin-sdk/mattermost-policy`、`plugin-sdk/feishu`、`plugin-sdk/feishu-conversation`、`plugin-sdk/feishu-setup`、`plugin-sdk/msteams`、`plugin-sdk/nextcloud-talk`、`plugin-sdk/nostr`、`plugin-sdk/telegram-command-ui`、`plugin-sdk/tlon`、`plugin-sdk/twitch`、`plugin-sdk/zalo`、`plugin-sdk/zalo-setup` | 已弃用的内置渠道兼容 / 辅助接口。新插件应导入通用 SDK 子路径或插件本地 barrel。 | + | 认证 / 插件专用辅助函数 | `plugin-sdk/github-copilot-login`、`plugin-sdk/github-copilot-token`、`plugin-sdk/diagnostics-otel`、`plugin-sdk/diagnostics-prometheus`、`plugin-sdk/diffs`、`plugin-sdk/llm-task`、`plugin-sdk/memory-core`、`plugin-sdk/memory-lancedb`、`plugin-sdk/opencode`、`plugin-sdk/thread-ownership`、`plugin-sdk/voice-call` | 内置功能 / 插件辅助接口；`plugin-sdk/github-copilot-token` 当前导出 `DEFAULT_COPILOT_API_BASE_URL`、`deriveCopilotApiBaseUrlFromToken` 和 `resolveCopilotApiToken` | diff --git a/docs/zh-CN/tools/thinking.md b/docs/zh-CN/tools/thinking.md index de7c4f97a..42b8d88f1 100644 --- a/docs/zh-CN/tools/thinking.md +++ b/docs/zh-CN/tools/thinking.md @@ -1,135 +1,136 @@ --- read_when: - - 调整 thinking、快速模式或详细输出指令的解析或默认值 -summary: '`/think`、`/fast`、`/verbose`、`/trace` 和 reasoning 可见性的指令语法' + - 调整思考、快速模式或详细模式的指令解析或默认值 +summary: '`/think`、`/fast`、`/verbose`、`/trace` 以及推理可见性的指令语法' title: 思考级别 x-i18n: - generated_at: "2026-04-27T12:56:52Z" + generated_at: "2026-04-27T13:19:40Z" model: gpt-5.4 provider: openai - source_hash: 29369485fc69e98bd6705128d360d66addd7a5057ddc01e4010820b73f48142c + source_hash: 7eaa5f397e1ecc327b8706f3fee8cd44e4986ddc23159e20e6d026911eb331e0 source_path: tools/thinking.md workflow: 15 --- ## 它的作用 -- 任意入站消息正文中的内联指令：`/t `、`/think:` 或 `/thinking `。 +- 可在任何入站消息正文中使用内联指令：`/t `、`/think:` 或 `/thinking `。 - 级别（别名）：`off | minimal | low | medium | high | xhigh | adaptive | max` - - minimal → “think” - - low → “think hard” - - medium → “think harder” - - high → “ultrathink”（最大预算） - - xhigh → “ultrathink+”（GPT-5.2+ 和 Codex 模型，以及 Anthropic Claude Opus 4.7 effort） - - adaptive → provider 管理的自适应 thinking（支持 Anthropic / Bedrock 上的 Claude 4.6、Anthropic Claude Opus 4.7，以及 Google Gemini dynamic thinking） - - max → provider 最大 reasoning（Anthropic Claude Opus 4.7；Ollama 会将其映射为其原生最高 `think` effort） - - `x-high`、`x_high`、`extra-high`、`extra high` 和 `extra_high` 都会映射为 `xhigh`。 + - minimal → “思考” + - low → “深入思考” + - medium → “更深入思考” + - high → “超深度思考”（最大预算） + - xhigh → “ultrathink+”（适用于 GPT-5.2+ 和 Codex 模型，以及 Anthropic Claude Opus 4.7 effort） + - adaptive → 由提供商管理的自适应思考（适用于 Anthropic/Bedrock 上的 Claude 4.6、Anthropic Claude Opus 4.7，以及 Google Gemini dynamic thinking） + - max → 提供商的最大推理级别（Anthropic Claude Opus 4.7；Ollama 会将其映射为其原生最高 `think` effort） + - `x-high`、`x_high`、`extra-high`、`extra high` 和 `extra_high` 会映射为 `xhigh`。 - `highest` 会映射为 `high`。 -- provider 说明： - - Thinking 菜单和选择器由 provider 配置档案驱动。Provider 插件会为所选模型声明精确的级别集合，包括诸如二元 `on` 之类的标签。 - - `adaptive`、`xhigh` 和 `max` 仅会针对支持它们的 provider / 模型配置档案显示。对于不受支持级别的类型化指令，会拒绝并返回该模型的有效选项。 - - 已存储但不受支持的现有级别会按 provider 配置档案等级重新映射。`adaptive` 在非自适应模型上会回退到 `medium`，而 `xhigh` 和 `max` 会回退到所选模型支持的最高非 `off` 级别。 - - 当未显式设置 thinking 级别时，Anthropic Claude 4.6 模型默认使用 `adaptive`。 - - Anthropic Claude Opus 4.7 不默认启用 adaptive thinking。其 API effort 默认值仍由 provider 决定，除非你显式设置 thinking 级别。 - - Anthropic Claude Opus 4.7 会将 `/think xhigh` 映射为 adaptive thinking 加上 `output_config.effort: "xhigh"`，因为 `/think` 是一个 thinking 指令，而 `xhigh` 是 Opus 4.7 的 effort 设置。 - - Anthropic Claude Opus 4.7 也暴露 `/think max`；它会映射到同一个由 provider 管理的最大 effort 路径。 - - 支持 thinking 的 Ollama 模型暴露 `/think low|medium|high|max`；`max` 会映射为原生 `think: "high"`，因为 Ollama 的原生 API 接受 `low`、`medium` 和 `high` effort 字符串。 - - OpenAI GPT 模型会根据模型特定的 Responses API effort 支持来映射 `/think`。`/think off` 仅在目标模型支持时才会发送 `reasoning.effort: "none"`；否则 OpenClaw 会省略禁用 reasoning 的载荷，而不是发送不受支持的值。 - - 过时的 OpenRouter Hunter Alpha 配置引用会跳过代理 reasoning 注入，因为那条已退役的路由可能会通过 reasoning 字段返回最终回答文本。 - - Google Gemini 会将 `/think adaptive` 映射为 Gemini 由 provider 管理的 dynamic thinking。Gemini 3 请求会省略固定的 `thinkingLevel`，而 Gemini 2.5 请求会发送 `thinkingBudget: -1`；固定级别仍会映射为该模型系列中最接近的 Gemini `thinkingLevel` 或预算。 - - 在与 Anthropic 兼容的流式路径上，MiniMax（`minimax/*`）默认使用 `thinking: { type: "disabled" }`，除非你在模型参数或请求参数中显式设置 thinking。这样可避免 MiniMax 的非原生 Anthropic 流格式泄露 `reasoning_content` 增量。 - - Z.AI（`zai/*`）仅支持二元 thinking（`on` / `off`）。任何非 `off` 的级别都视为 `on`（映射为 `low`）。 - - Moonshot（`moonshot/*`）会将 `/think off` 映射为 `thinking: { type: "disabled" }`，并将任何非 `off` 级别映射为 `thinking: { type: "enabled" }`。启用 thinking 时，Moonshot 仅接受 `tool_choice` 为 `auto|none`；OpenClaw 会将不兼容的值规范化为 `auto`。 +- 提供商说明： + - 思考菜单和选择器由 provider 配置文件驱动。提供商插件会为所选模型声明精确的级别集合，包括如二元 `on` 这样的标签。 + - 仅当 provider/模型配置文件支持时，才会展示 `adaptive`、`xhigh` 和 `max`。如果输入了不受支持级别的类型化指令，将拒绝该指令，并返回该模型的有效选项。 + - 已存储但不受支持的旧级别会按 provider 配置文件的等级重新映射。`adaptive` 在非自适应模型上会回退为 `medium`，而 `xhigh` 和 `max` 会回退为所选模型支持的最高非 `off` 级别。 + - 当未显式设置思考级别时，Anthropic Claude 4.6 模型默认使用 `adaptive`。 + - Anthropic Claude Opus 4.7 不默认使用 adaptive thinking。除非你显式设置思考级别，否则其 API effort 默认值仍由 provider 决定。 + - Anthropic Claude Opus 4.7 会将 `/think xhigh` 映射为 adaptive thinking 加 `output_config.effort: "xhigh"`，因为 `/think` 是思考指令，而 `xhigh` 是 Opus 4.7 的 effort 设置。 + - Anthropic Claude Opus 4.7 还支持 `/think max`；它会映射到相同的 provider 管理的最大 effort 路径。 + - 支持思考的 Ollama 模型支持 `/think low|medium|high|max`；`max` 会映射为原生 `think: "high"`，因为 Ollama 的原生 API 接受 `low`、`medium` 和 `high` 这几种 effort 字符串。 + - OpenAI GPT 模型会根据具体模型对 Responses API effort 的支持情况来映射 `/think`。仅当目标模型支持时，`/think off` 才会发送 `reasoning.effort: "none"`；否则 OpenClaw 会省略禁用推理的负载，而不是发送不受支持的值。 + - 过期配置的 OpenRouter Hunter Alpha 引用会跳过代理推理注入，因为该已退役路由可能会通过推理字段返回最终答案文本。 + - Google Gemini 会将 `/think adaptive` 映射为 Gemini 由提供商管理的 dynamic thinking。Gemini 3 请求会省略固定的 `thinkingLevel`，而 Gemini 2.5 请求会发送 `thinkingBudget: -1`；固定级别仍会映射为该模型系列最接近的 Gemini `thinkingLevel` 或预算。 + - Anthropic 兼容流式路径上的 MiniMax（`minimax/*`）默认使用 `thinking: { type: "disabled" }`，除非你在模型参数或请求参数中显式设置 thinking。这可避免 MiniMax 非原生 Anthropic 流格式中泄露 `reasoning_content` 增量。 + - Z.AI（`zai/*`）仅支持二元思考（`on`/`off`）。任何非 `off` 级别都会视为 `on`（映射为 `low`）。 + - Moonshot（`moonshot/*`）会将 `/think off` 映射为 `thinking: { type: "disabled" }`，并将任何非 `off` 级别映射为 `thinking: { type: "enabled" }`。启用 thinking 时，Moonshot 仅接受 `tool_choice` 为 `auto|none`；OpenClaw 会将不兼容的值标准化为 `auto`。 ## 解析顺序 -1. 消息上的内联指令（仅作用于该条消息）。 -2. 会话覆盖值（通过发送仅包含指令的消息来设置）。 +1. 消息上的内联指令（仅对该条消息生效）。 +2. 会话覆盖值（通过发送仅包含指令的消息设置）。 3. 每个智能体的默认值（配置中的 `agents.list[].thinkingDefault`）。 4. 全局默认值（配置中的 `agents.defaults.thinkingDefault`）。 -5. 回退：优先使用 provider 声明的默认值；否则，支持 reasoning 的模型会解析为 `medium` 或该模型支持的最接近非 `off` 级别，而不支持 reasoning 的模型则保持为 `off`。 +5. 回退：如果可用，则使用 provider 声明的默认值；否则，支持推理的模型会解析为 `medium` 或该模型支持的最接近的非 `off` 级别，不支持推理的模型则保持 `off`。 ## 设置会话默认值 - 发送一条**仅包含指令**的消息（允许空白字符），例如 `/think:medium` 或 `/t high`。 -- 该设置会固定到当前会话（默认按发送者区分）；可通过 `/think:off` 或会话空闲重置来清除。 -- 会发送确认回复（`Thinking level set to high.` / `Thinking disabled.`）。如果级别无效（例如 `/thinking big`），命令会被拒绝并返回提示，同时不会更改会话状态。 -- 发送不带参数的 `/think`（或 `/think:`）可查看当前 thinking 级别。 +- 该设置会在当前会话中保持生效（默认按发送者区分）；可通过 `/think:off` 或会话空闲重置来清除。 +- 会发送确认回复（`Thinking level set to high.` / `Thinking disabled.`）。如果级别无效（例如 `/thinking big`），命令会被拒绝，并给出提示，同时不会更改会话状态。 +- 发送不带参数的 `/think`（或 `/think:`）即可查看当前思考级别。 ## 按智能体应用 -- **嵌入式 Pi**：解析出的级别会传递给进程内 Pi 智能体运行时。 +- **嵌入式 Pi**：解析后的级别会传递给进程内的 Pi 智能体运行时。 -## 快速模式（/fast） +## 快速模式（`/fast`） - 级别：`on|off`。 -- 仅指令消息会切换会话快速模式覆盖值，并回复 `Fast mode enabled.` / `Fast mode disabled.`。 -- 发送不带模式的 `/fast`（或 `/fast status`）可查看当前生效的快速模式状态。 -- OpenClaw 会按以下顺序解析快速模式： - 1. 内联 / 仅指令 `/fast on|off` +- 仅含指令的消息会切换会话快速模式覆盖值，并回复 `Fast mode enabled.` / `Fast mode disabled.`。 +- 发送不带模式的 `/fast`（或 `/fast status`）即可查看当前生效的快速模式状态。 +- OpenClaw 按以下顺序解析快速模式： + 1. 内联/仅指令 `/fast on|off` 2. 会话覆盖值 3. 每个智能体的默认值（`agents.list[].fastModeDefault`） 4. 每个模型的配置：`agents.defaults.models["/"].params.fastMode` 5. 回退：`off` -- 对于 `openai/*`，快速模式会通过在受支持的 Responses 请求上发送 `service_tier=priority`，映射为 OpenAI 优先处理。 -- 对于 `openai-codex/*`，快速模式会在 Codex Responses 上发送同样的 `service_tier=priority` 标志。OpenClaw 会在这两种认证路径之间共享同一个 `/fast` 开关。 -- 对于直接发送到 `api.anthropic.com` 的公开 `anthropic/*` 请求（包括经 OAuth 认证的流量），快速模式会映射为 Anthropic 服务层级：`/fast on` 设为 `service_tier=auto`，`/fast off` 设为 `service_tier=standard_only`。 -- 对于走 Anthropic 兼容路径的 `minimax/*`，`/fast on`（或 `params.fastMode: true`）会将 `MiniMax-M2.7` 重写为 `MiniMax-M2.7-highspeed`。 -- 当显式设置了 Anthropic `serviceTier` / `service_tier` 模型参数时，它会在两者同时设置时覆盖快速模式默认值。对于非 Anthropic 代理 `baseUrl`，OpenClaw 仍会跳过 Anthropic 服务层级注入。 +- 对于 `openai/*`，快速模式会通过在受支持的 Responses 请求上发送 `service_tier=priority` 来映射为 OpenAI 优先处理。 +- 对于 `openai-codex/*`，快速模式会在 Codex Responses 上发送同样的 `service_tier=priority` 标志。OpenClaw 会在两种认证路径之间共享同一个 `/fast` 开关。 +- 对于直接公共 `anthropic/*` 请求，包括发送到 `api.anthropic.com` 的 OAuth 认证流量，快速模式会映射到 Anthropic 服务层级：`/fast on` 设置 `service_tier=auto`，`/fast off` 设置 `service_tier=standard_only`。 +- 对于 Anthropic 兼容路径上的 `minimax/*`，`/fast on`（或 `params.fastMode: true`）会将 `MiniMax-M2.7` 重写为 `MiniMax-M2.7-highspeed`。 +- 当显式设置了 Anthropic `serviceTier` / `service_tier` 模型参数时，它会在两者同时设置时覆盖快速模式默认值。对于非 Anthropic 代理基础 URL，OpenClaw 仍会跳过注入 Anthropic 服务层级。 - 仅当快速模式启用时，`/status` 才会显示 `Fast`。 -## 详细输出指令（`/verbose` 或 `/v`） +## 详细模式指令（`/verbose` 或 `/v`） - 级别：`on`（最简）| `full` | `off`（默认）。 -- 仅指令消息会切换会话详细输出，并回复 `Verbose logging enabled.` / `Verbose logging disabled.`；无效级别会返回提示且不更改状态。 -- `/verbose off` 会存储一个显式的会话覆盖值；可在 Sessions UI 中通过选择 `inherit` 清除。 -- 内联指令仅影响该条消息；否则会应用会话 / 全局默认值。 -- 发送不带参数的 `/verbose`（或 `/verbose:`）可查看当前 verbose 级别。 -- 当 verbose 开启时，输出结构化工具结果的智能体（Pi、其他 JSON 智能体）会将每次工具调用作为单独的仅元数据消息回发，并在可用时加上前缀 ` : `（路径 / 命令）。这些工具摘要会在每个工具启动时立即发送（单独气泡），而不是作为流式增量发送。 -- 工具失败摘要在普通模式下仍然可见，但原始错误详情后缀会被隐藏，除非 verbose 为 `on` 或 `full`。 -- 当 verbose 为 `full` 时，工具输出也会在完成后转发（单独气泡，并截断到安全长度）。如果你在运行过程中切换 `/verbose on|full|off`，后续工具气泡会遵循新的设置。 +- 仅含指令的消息会切换会话详细模式，并回复 `Verbose logging enabled.` / `Verbose logging disabled.`；无效级别会返回提示，但不会更改状态。 +- `/verbose off` 会存储一个显式的会话覆盖值；可在 Sessions UI 中选择 `inherit` 来清除它。 +- 内联指令仅对该条消息生效；否则会应用会话/全局默认值。 +- 发送不带参数的 `/verbose`（或 `/verbose:`）即可查看当前详细级别。 +- 当 verbose 开启时，会输出结构化工具结果的智能体（Pi、其他 JSON 智能体）会将每次工具调用作为单独的仅元数据消息发回；如果可用，会以 ` : ` 作为前缀（路径/命令）。这些工具摘要会在每个工具启动时立即发送（独立消息气泡），而不是作为流式增量发送。 +- 工具失败摘要在普通模式下仍然可见，但除非 verbose 为 `on` 或 `full`，否则会隐藏原始错误详情后缀。 +- 当 verbose 为 `full` 时，工具输出也会在完成后转发（独立消息气泡，截断到安全长度）。如果你在运行过程中切换 `/verbose on|full|off`，后续的工具消息气泡会遵循新的设置。 ## 插件 trace 指令（`/trace`） - 级别：`on` | `off`（默认）。 -- 仅指令消息会切换会话插件 trace 输出，并回复 `Plugin trace enabled.` / `Plugin trace disabled.`。 -- 内联指令仅影响该条消息；否则会应用会话 / 全局默认值。 -- 发送不带参数的 `/trace`（或 `/trace:`）可查看当前 trace 级别。 -- `/trace` 比 `/verbose` 更窄：它只暴露由插件拥有的 trace / debug 行，例如 Active Memory 调试摘要。 -- Trace 行可能出现在 `/status` 中，也可能在正常助手回复之后作为后续诊断消息出现。 +- 仅含指令的消息会切换会话插件 trace 输出，并回复 `Plugin trace enabled.` / `Plugin trace disabled.`。 +- 内联指令仅对该条消息生效；否则会应用会话/全局默认值。 +- 发送不带参数的 `/trace`（或 `/trace:`）即可查看当前 trace 级别。 +- `/trace` 比 `/verbose` 更窄：它只暴露插件自身的 trace/debug 行，例如 Active Memory 调试摘要。 +- Trace 行可能会出现在 `/status` 中，也可能在正常助手回复后作为后续诊断消息出现。 -## Reasoning 可见性（`/reasoning`） +## 推理可见性（`/reasoning`） - 级别：`on|off|stream`。 -- 仅指令消息会切换是否在回复中显示 thinking 块。 -- 启用时，reasoning 会作为一条**单独消息**发送，并以 `Reasoning:` 开头。 -- `stream`（仅 Telegram）：在生成回复期间，将 reasoning 流式写入 Telegram 草稿气泡中，然后发送不含 reasoning 的最终回答。 +- 仅含指令的消息会切换是否在回复中显示 thinking 块。 +- 启用后，推理会作为**单独一条消息**发送，并以 `Reasoning:` 为前缀。 +- `stream`（仅限 Telegram）：会在回复生成期间将推理流式写入 Telegram 草稿气泡，随后发送不含推理的最终答案。 - 别名：`/reason`。 -- 发送不带参数的 `/reasoning`（或 `/reasoning:`）可查看当前 reasoning 级别。 -- 解析顺序：内联指令，然后是会话覆盖值，然后是每个智能体的默认值（`agents.list[].reasoningDefault`），最后回退为 `off`。 +- 发送不带参数的 `/reasoning`（或 `/reasoning:`）即可查看当前推理级别。 +- 解析顺序：内联指令，然后是会话覆盖值，再然后是每个智能体的默认值（`agents.list[].reasoningDefault`），最后回退为 `off`。 -格式错误的本地模型 reasoning 标签会被保守处理。闭合的 `...` 块在普通回复中仍会隐藏，而在已出现可见文本之后出现的未闭合 reasoning 也会被隐藏。如果一条回复被单个未闭合开始标签完整包裹，且否则会作为空文本发送，OpenClaw 会移除该格式错误的开始标签，并发送剩余文本。 +格式错误的本地模型推理标签会被保守处理。闭合的 `...` 块在普通回复中会保持隐藏；在已有可见文本之后出现的未闭合推理内容也会被隐藏。如果回复整体被单个未闭合起始标签包裹，且否则会导致发送空文本，OpenClaw 会移除这个格式错误的起始标签，并发送剩余文本。 -## 相关 +## 相关内容 -- Elevated mode 文档位于[Elevated mode](/zh-CN/tools/elevated)。 +- Elevated mode 文档见 [Elevated mode](/zh-CN/tools/elevated)。 -## 心跳 +## Heartbeats -- 心跳探测正文是已配置的心跳提示词（默认：`Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`）。心跳消息中的内联指令会照常应用（但应避免通过心跳更改会话默认值）。 -- 心跳传递默认仅发送最终载荷。如需同时发送单独的 `Reasoning:` 消息（如可用），请设置 `agents.defaults.heartbeat.includeReasoning: true` 或每个智能体的 `agents.list[].heartbeat.includeReasoning: true`。 +- Heartbeat 探测消息正文为配置的 heartbeat prompt（默认值：`Read HEARTBEAT.md if it exists (workspace context). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.`）。Heartbeat 消息中的内联指令会照常生效（但应避免通过 heartbeat 更改会话默认值）。 +- Heartbeat 发送默认仅包含最终负载。如需同时发送单独的 `Reasoning:` 消息（如果可用），请设置 `agents.defaults.heartbeat.includeReasoning: true` 或每个智能体的 `agents.list[].heartbeat.includeReasoning: true`。 ## Web 聊天 UI -- Web 聊天 thinking 选择器在页面加载时会从入站会话存储 / 配置中镜像该会话已存储的级别。 -- 选择其他级别会立即通过 `sessions.patch` 写入会话覆盖值；它不会等待下一次发送，也不是一次性的 `thinkingOnce` 覆盖值。 -- 第一个选项始终是 `Default ()`，其中解析出的默认值来自当前会话模型的 provider thinking 配置档案，以及 `/status` 和 `session_status` 使用的同一套回退逻辑。 -- 选择器使用 gateway 会话行 / 默认值返回的 `thinkingLevels`，并将 `thinkingOptions` 保留为旧版标签列表。浏览器 UI 不会保留自己的 provider 正则列表；模型特定级别集合由插件负责。 -- `/think:` 仍然有效，并会更新同一个已存储的会话级别，因此聊天指令和选择器会保持同步。 +- Web 聊天中的思考选择器会在页面加载时，镜像入站会话存储/配置中该会话的已存储级别。 +- 选择其他级别会立即通过 `sessions.patch` 写入会话覆盖值；它不会等待下一次发送，也不是一次性的 `thinkingOnce` 覆盖。 +- 第一个选项始终是 `Default ()`，其中解析后的默认值来自活动会话模型的 provider thinking 配置文件，以及 `/status` 和 `session_status` 使用的同一套回退逻辑。 +- 选择器使用 Gateway 网关 会话行/默认值返回的 `thinkingLevels`，并保留 `thinkingOptions` 作为旧版标签列表。浏览器 UI 不会维护自己的 provider 正则列表；模型专属级别集由插件负责。 +- `/think:` 仍然可用，并会更新相同的已存储会话级别，因此聊天指令与选择器始终保持同步。 -## Provider 配置档案 +## 提供商配置文件 -- Provider 插件可暴露 `resolveThinkingProfile(ctx)` 以定义该模型支持的级别和默认值。 -- 每个配置档案级别都有一个已存储的规范 `id`（`off`、`minimal`、`low`、`medium`、`high`、`xhigh`、`adaptive` 或 `max`），并且可以包含一个显示用 `label`。二元 provider 使用 `{ id: "low", label: "on" }`。 -- 已发布的旧版钩子（`supportsXHighThinking`、`isBinaryThinking` 和 `resolveDefaultThinkingLevel`）仍保留为兼容性适配器，但新的自定义级别集合应使用 `resolveThinkingProfile`。 -- Gateway 网关行 / 默认值会暴露 `thinkingLevels`、`thinkingOptions` 和 `thinkingDefault`，以便 ACP / 聊天客户端渲染与运行时校验所使用的同一配置档案 ID 和标签。 +- 提供商插件可暴露 `resolveThinkingProfile(ctx)` 以定义模型支持的级别和默认值。 +- 每个配置文件级别都有一个已存储的规范 `id`（`off`、`minimal`、`low`、`medium`、`high`、`xhigh`、`adaptive` 或 `max`），并且可以包含一个显示 `label`。二元提供商使用 `{ id: "low", label: "on" }`。 +- 需要验证显式思考覆盖值的工具插件应使用 `api.runtime.agent.resolveThinkingPolicy({ provider, model })` 和 `api.runtime.agent.normalizeThinkingLevel(...)`；不应维护自己的 provider/模型级别列表。 +- 已发布的旧版钩子（`supportsXHighThinking`、`isBinaryThinking` 和 `resolveDefaultThinkingLevel`）仍保留为兼容适配器，但新的自定义级别集应使用 `resolveThinkingProfile`。 +- Gateway 网关 行/默认值会暴露 `thinkingLevels`、`thinkingOptions` 和 `thinkingDefault`，以便 ACP/聊天客户端渲染与运行时验证所使用的相同配置文件 id 和标签。