chore(i18n): refresh zh-CN translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
a3e1071978
commit
cf3b5bfdd7
166
docs/zh-CN/ci.md
166
docs/zh-CN/ci.md
File diff suppressed because one or more lines are too long
@ -1,36 +1,36 @@
|
||||
---
|
||||
read_when:
|
||||
- 你想将 QMD 设置为你的内存后端
|
||||
- 你想要高级内存功能，例如重排序或额外的索引路径
|
||||
summary: 本地优先搜索边车，支持 BM25、向量、重排序和查询扩展
|
||||
title: QMD 内存引擎
|
||||
- 你想将 QMD 设置为你的记忆后端
|
||||
- 你想要高级记忆功能，例如重排序或额外的索引路径
|
||||
summary: 本地优先的搜索 sidecar，支持 BM25、向量、重排序和查询扩展
|
||||
title: QMD 记忆引擎
|
||||
x-i18n:
|
||||
generated_at: "2026-04-27T13:13:04Z"
|
||||
generated_at: "2026-04-27T13:31:44Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: f19cfee3cd94ee0bfff97f2758e788790ade628f89ecdf99bf954e2894a2e7e8
|
||||
source_hash: 10115a298b5966847e037e567efbc8cb2823afe658a408e18a683d1c6baebe99
|
||||
source_path: concepts/memory-qmd.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
[QMD](https://github.com/tobi/qmd) 是一个本地优先的搜索边车，与 OpenClaw 一起运行。它将 BM25、向量搜索和重排序整合到单个二进制文件中，还可以索引超出你工作区内存文件范围的内容。
|
||||
[QMD](https://github.com/tobi/qmd) 是一个与 OpenClaw 一起运行的本地优先搜索 sidecar。它将 BM25、向量搜索和重排序整合到单个二进制程序中，还可以为你的工作区记忆文件之外的内容建立索引。
|
||||
|
||||
## 相比内置功能，它增加了什么
|
||||
## 相比内置引擎增加了什么
|
||||
|
||||
- **重排序和查询扩展**，以获得更好的召回效果。
|
||||
- **索引额外目录** —— 项目文档、团队笔记、磁盘上的任何内容。
|
||||
- **索引额外目录** —— 项目文档、团队笔记，以及磁盘上的任何内容。
|
||||
- **索引会话转录** —— 回忆更早的对话。
|
||||
- **完全本地化** —— 配合可选的 `node-llama-cpp` 运行时包运行，并自动下载 GGUF 模型。
|
||||
- **完全本地运行** —— 通过可选的 `node-llama-cpp` 运行时包运行，并自动下载 GGUF 模型。
|
||||
- **自动回退** —— 如果 QMD 不可用，OpenClaw 会无缝回退到内置引擎。
|
||||
|
||||
## 入门指南
|
||||
|
||||
### 前提条件
|
||||
### 先决条件
|
||||
|
||||
- 安装 QMD：`npm install -g @tobilu/qmd` 或 `bun install -g @tobilu/qmd`
|
||||
- 允许扩展的 SQLite 构建版本（在 macOS 上使用 `brew install sqlite`）。
|
||||
- 允许扩展的 SQLite 构建版本（macOS 上可使用 `brew install sqlite`）。
|
||||
- QMD 必须位于 Gateway 网关的 `PATH` 中。
|
||||
- macOS 和 Linux 开箱即用。Windows 最佳支持方式是通过 WSL2。
|
||||
- macOS 和 Linux 可开箱即用。Windows 最佳支持方式是通过 WSL2。
|
||||
|
||||
### 启用
|
||||
|
||||
@ -42,23 +42,23 @@ x-i18n:
|
||||
}
|
||||
```
|
||||
|
||||
OpenClaw 会在 `~/.openclaw/agents/<agentId>/qmd/` 下创建一个独立自包含的 QMD 主目录，并自动管理边车生命周期 —— 集合、更新和嵌入运行都会为你处理。它会优先使用当前的 QMD 集合和 MCP 查询形状，但在需要时仍会回退到旧版的 `--mask` 集合标志和更早的 MCP 工具名称。启动时的协调过程还会在检测到存在同名旧版 QMD 集合时，将过时的托管集合重新创建为其规范模式。
|
||||
OpenClaw 会在 `~/.openclaw/agents/<agentId>/qmd/` 下创建一个自包含的 QMD 主目录，并自动管理 sidecar 的生命周期 —— 集合、更新和嵌入运行都会由它代劳。它会优先使用当前的 QMD collection 和 MCP query 形状，但在需要时仍会回退到备用 collection pattern 标志和较旧的 MCP 工具名称。启动时的协调还会在检测到仍存在同名旧 QMD collection 时，将过时的受管 collection 重新创建为其规范模式。
|
||||
|
||||
## 边车如何工作
|
||||
## sidecar 的工作方式
|
||||
|
||||
- OpenClaw 会根据你的工作区内存文件以及所有已配置的 `memory.qmd.paths` 创建集合，然后在启动时和周期性地运行 `qmd update`（默认每 5 分钟一次）。语义模式还会运行 `qmd embed`。
|
||||
- 默认工作区集合会跟踪 `MEMORY.md` 以及 `memory/` 目录树。小写的 `memory.md` 不会作为根内存文件被索引。
|
||||
- 启动刷新会在后台运行，因此不会阻塞聊天启动。
|
||||
- 搜索会使用已配置的 `searchMode`（默认值：`search`；也支持 `vsearch` 和 `query`）。`search` 仅使用 BM25，因此 OpenClaw 会在该模式下跳过语义向量就绪探测和嵌入维护。如果某个模式失败，OpenClaw 会使用 `qmd query` 重试。
|
||||
- OpenClaw 会根据你的工作区记忆文件以及所有已配置的 `memory.qmd.paths` 创建 collection，然后在启动时和周期性地运行 `qmd update`（默认每 5 分钟一次）。语义模式还会运行 `qmd embed`。
|
||||
- 默认工作区 collection 会跟踪 `MEMORY.md` 和 `memory/` 目录树。小写的 `memory.md` 不会作为根记忆文件建立索引。
|
||||
- 启动时刷新会在后台进行，因此不会阻塞聊天启动。
|
||||
- 搜索会使用已配置的 `searchMode`（默认：`search`；也支持 `vsearch` 和 `query`）。`search` 仅使用 BM25，因此 OpenClaw 会在该模式下跳过语义向量就绪探测和嵌入维护。如果某个模式失败，OpenClaw 会使用 `qmd query` 重试。
|
||||
- 如果 QMD 完全失败，OpenClaw 会回退到内置的 SQLite 引擎。
|
||||
|
||||
<Info>
|
||||
第一次搜索可能会较慢 —— QMD 会在第一次运行 `qmd query` 时自动下载用于重排序和查询扩展的 GGUF 模型（约 2 GB）。
|
||||
第一次搜索可能会较慢 —— QMD 会在首次运行 `qmd query` 时自动下载用于重排序和查询扩展的 GGUF 模型（约 2 GB）。
|
||||
</Info>
|
||||
|
||||
## 模型覆盖
|
||||
|
||||
QMD 模型环境变量会从 Gateway 网关进程中原样透传，因此你可以在不添加新的 OpenClaw 配置的情况下全局调优 QMD：
|
||||
QMD 的模型环境变量会从 Gateway 网关进程原样透传，因此你可以在不新增 OpenClaw 配置的情况下全局调优 QMD：
|
||||
|
||||
```bash
|
||||
export QMD_EMBED_MODEL="hf:Qwen/Qwen3-Embedding-0.6B-GGUF/Qwen3-Embedding-0.6B-Q8_0.gguf"
|
||||
@ -66,11 +66,11 @@ export QMD_RERANK_MODEL="/absolute/path/to/reranker.gguf"
|
||||
export QMD_GENERATE_MODEL="/absolute/path/to/generator.gguf"
|
||||
```
|
||||
|
||||
更改嵌入模型后，请重新运行嵌入，以便索引与新的向量空间匹配。
|
||||
更改嵌入模型后，请重新运行嵌入，以确保索引与新的向量空间匹配。
|
||||
|
||||
## 索引额外路径
|
||||
## 为额外路径建立索引
|
||||
|
||||
让 QMD 指向其他目录，使其内容可被搜索：
|
||||
将 QMD 指向其他目录，使其可被搜索：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -83,9 +83,9 @@ export QMD_GENERATE_MODEL="/absolute/path/to/generator.gguf"
|
||||
}
|
||||
```
|
||||
|
||||
来自额外路径的片段会在搜索结果中显示为 `qmd/<collection>/<relative-path>`。`memory_get` 能识别此前缀，并从正确的集合根目录读取内容。
|
||||
来自额外路径的片段会在搜索结果中显示为 `qmd/<collection>/<relative-path>`。`memory_get` 能识别此前缀，并从正确的 collection 根目录读取内容。
|
||||
|
||||
## 索引会话转录
|
||||
## 为会话转录建立索引
|
||||
|
||||
启用会话索引以回忆更早的对话：
|
||||
|
||||
@ -100,11 +100,11 @@ export QMD_GENERATE_MODEL="/absolute/path/to/generator.gguf"
|
||||
}
|
||||
```
|
||||
|
||||
转录会以经过清理的用户/助手轮次形式导出到专用的 QMD 集合中，位置在 `~/.openclaw/agents/<id>/qmd/sessions/`。
|
||||
转录会作为已清理的 User/Assistant 轮次导出到专用的 QMD collection 中，路径为 `~/.openclaw/agents/<id>/qmd/sessions/`。
|
||||
|
||||
## 搜索范围
|
||||
|
||||
默认情况下，QMD 搜索结果会在私信和渠道会话中显示（不包括群组）。配置 `memory.qmd.scope` 可更改此行为：
|
||||
默认情况下，QMD 搜索结果会显示在直接会话和渠道会话中（不包括群组）。通过配置 `memory.qmd.scope` 来更改此行为：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -119,50 +119,50 @@ export QMD_GENERATE_MODEL="/absolute/path/to/generator.gguf"
|
||||
}
|
||||
```
|
||||
|
||||
当范围规则拒绝某次搜索时，OpenClaw 会记录一条警告，其中包含推导出的渠道和聊天类型，以便更容易调试空结果。
|
||||
当范围规则拒绝一次搜索时，OpenClaw 会记录一条警告，其中包含推导出的渠道和聊天类型，以便更容易调试空结果问题。
|
||||
|
||||
## 引用
|
||||
|
||||
当 `memory.citations` 为 `auto` 或 `on` 时，搜索片段会包含一个 `Source: <path#line>` 页脚。将 `memory.citations = "off"` 可省略该页脚，同时仍会在内部将路径传递给智能体。
|
||||
当 `memory.citations` 为 `auto` 或 `on` 时，搜索片段会包含 `Source: <path#line>` 页脚。将 `memory.citations = "off"` 可省略该页脚，同时仍会在内部将路径传递给智能体。
|
||||
|
||||
## 何时使用
|
||||
|
||||
当你需要以下能力时，请选择 QMD：
|
||||
|
||||
- 用重排序获得更高质量的结果。
|
||||
- 通过重排序获得更高质量的结果。
|
||||
- 搜索工作区之外的项目文档或笔记。
|
||||
- 回忆过去的会话对话。
|
||||
- 完全本地搜索，无需 API 密钥。
|
||||
- 完全本地搜索且无需 API 密钥。
|
||||
|
||||
对于更简单的设置，[内置引擎](/zh-CN/concepts/memory-builtin) 在不需要额外依赖的情况下也能很好地工作。
|
||||
对于更简单的设置，[内置引擎](/zh-CN/concepts/memory-builtin) 在无需额外依赖的情况下也能很好地工作。
|
||||
|
||||
## 故障排除
|
||||
|
||||
**找不到 QMD？** 请确保该二进制文件位于 Gateway 网关的 `PATH` 中。如果 OpenClaw 作为服务运行，请创建一个符号链接：
|
||||
**找不到 QMD？** 请确认该二进制程序位于 Gateway 网关的 `PATH` 中。如果 OpenClaw 作为服务运行，请创建符号链接：
|
||||
`sudo ln -s ~/.bun/bin/qmd /usr/local/bin/qmd`。
|
||||
|
||||
**第一次搜索很慢？** QMD 会在首次使用时下载 GGUF 模型。可使用与 OpenClaw 相同的 XDG 目录运行 `qmd query "test"` 进行预热。
|
||||
**第一次搜索很慢？** QMD 会在首次使用时下载 GGUF 模型。可使用与 OpenClaw 相同的 XDG 目录，通过 `qmd query "test"` 进行预热。
|
||||
|
||||
**仅 BM25 的 QMD 仍在尝试构建 llama.cpp？** 请设置
|
||||
`memory.qmd.searchMode = "search"`。OpenClaw 会将该模式视为纯词法模式，不会运行 QMD 向量状态探测或嵌入维护，并将语义就绪检查留给 `vsearch` 或 `query` 配置。
|
||||
`memory.qmd.searchMode = "search"`。OpenClaw 会将该模式视为纯词法搜索，不会运行 QMD 向量状态探测或嵌入维护，并将语义就绪检查留给 `vsearch` 或 `query` 设置。
|
||||
|
||||
**搜索超时？** 增大 `memory.qmd.limits.timeoutMs`（默认值：4000ms）。
|
||||
对于较慢的硬件，可设置为 `120000`。
|
||||
**搜索超时？** 请增大 `memory.qmd.limits.timeoutMs`（默认：4000ms）。
|
||||
对于较慢的硬件，请设置为 `120000`。
|
||||
|
||||
**群聊中结果为空？** 检查 `memory.qmd.scope` —— 默认情况下仅允许私信和渠道会话。
|
||||
**群聊中结果为空？** 请检查 `memory.qmd.scope` —— 默认仅允许直接会话和渠道会话。
|
||||
|
||||
**根内存搜索突然变得过于宽泛？** 重启 Gateway 网关或等待下次启动协调。检测到同名冲突时，OpenClaw 会将过时的托管集合重新创建为规范的 `MEMORY.md` 和 `memory/` 模式。
|
||||
**根记忆搜索突然变得过宽？** 重启 Gateway 网关，或等待下一次启动时协调。OpenClaw 会在检测到同名冲突时，将过时的受管 collection 重新创建为规范的 `MEMORY.md` 和 `memory/` 模式。
|
||||
|
||||
**工作区中可见的临时仓库导致 `ENAMETOOLONG` 或索引损坏？**
|
||||
QMD 遍历当前遵循底层 QMD 扫描器的行为，而不是 OpenClaw 内置的符号链接规则。在 QMD 提供安全处理循环遍历或显式排除控制之前，请将临时 monorepo 检出保存在诸如 `.tmp/` 之类的隐藏目录下，或放在已索引 QMD 根目录之外。
|
||||
**工作区可见的临时仓库导致 `ENAMETOOLONG` 或索引损坏？**
|
||||
QMD 遍历当前遵循底层 QMD 扫描器的行为，而不是 OpenClaw 内置的符号链接规则。在 QMD 提供安全的循环遍历或显式排除控制之前，请将临时 monorepo 检出保存在诸如 `.tmp/` 之类的隐藏目录下，或放在已建立索引的 QMD 根目录之外。
|
||||
|
||||
## 配置
|
||||
|
||||
有关完整配置项（`memory.qmd.*`）、搜索模式、更新间隔、范围规则以及所有其他可调项，请参阅
|
||||
[内存配置参考](/zh-CN/reference/memory-config)。
|
||||
要了解完整配置项（`memory.qmd.*`）、搜索模式、更新间隔、范围规则以及所有其他可调参数，请参阅
|
||||
[记忆配置参考](/zh-CN/reference/memory-config)。
|
||||
|
||||
## 相关内容
|
||||
|
||||
- [内存概览](/zh-CN/concepts/memory)
|
||||
- [内置内存引擎](/zh-CN/concepts/memory-builtin)
|
||||
- [Honcho 内存](/zh-CN/concepts/memory-honcho)
|
||||
- [记忆概览](/zh-CN/concepts/memory)
|
||||
- [内置记忆引擎](/zh-CN/concepts/memory-builtin)
|
||||
- [Honcho 记忆](/zh-CN/concepts/memory-honcho)
|
||||
|
||||
@ -2,42 +2,42 @@
|
||||
read_when:
|
||||
- 你维护一个 OpenClaw 插件
|
||||
- 你看到一个插件兼容性警告
|
||||
- 你正在规划插件 SDK 或清单迁移
|
||||
- 你正在规划一个插件 SDK 或清单迁移
|
||||
summary: 插件兼容性契约、弃用元数据和迁移预期
|
||||
title: 插件兼容性
|
||||
x-i18n:
|
||||
generated_at: "2026-04-26T11:10:53Z"
|
||||
generated_at: "2026-04-27T13:31:45Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 3b4e11dc57c29eac72844b91bec75a9d48005bbd3c89a2a9d7a5634ab782e5fc
|
||||
source_hash: bfe6896830a9493660b064a17ee2e082ae5bf5b43222a5652f0b37116332e997
|
||||
source_path: plugins/compatibility.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
OpenClaw 会在移除旧插件契约之前，通过具名兼容适配器继续接通较旧的插件契约。这样可以在 SDK、清单、设置、配置和智能体运行时契约演进期间，保护现有的内置插件和外部插件。
|
||||
OpenClaw 会通过具名兼容性适配器继续保留较旧的插件契约，然后再移除它们。这可以在 SDK、清单、设置、配置和智能体运行时契约演进期间，保护现有的内置插件和外部插件。
|
||||
|
||||
## 兼容性注册表
|
||||
|
||||
插件兼容性契约记录在核心注册表 `src/plugins/compat/registry.ts` 中。
|
||||
插件兼容性契约会在核心注册表 `src/plugins/compat/registry.ts` 中进行跟踪。
|
||||
|
||||
每条记录包含：
|
||||
每条记录都包含：
|
||||
|
||||
- 稳定的兼容性代码
|
||||
- 状态：`active`、`deprecated`、`removal-pending` 或 `removed`
|
||||
- 所有者：SDK、配置、设置、渠道、提供商、插件执行、智能体运行时或核心
|
||||
- 所有者：SDK、配置、设置、渠道、提供商、插件执行、Agent Runtimes 或核心
|
||||
- 适用时的引入日期和弃用日期
|
||||
- 替代指引
|
||||
- 覆盖旧行为和新行为的文档、诊断信息和测试
|
||||
- 替代方案指引
|
||||
- 涵盖旧行为和新行为的文档、诊断和测试
|
||||
|
||||
该注册表是维护者规划和未来插件检查器校验的来源。如果面向插件的行为发生变化，请在添加适配器的同一变更中添加或更新兼容性记录。
|
||||
该注册表是维护者进行规划和未来插件检查器校验的依据。如果某项面向插件的行为发生变化，请在添加适配器的同一次变更中添加或更新对应的兼容性记录。
|
||||
|
||||
Doctor 修复和迁移兼容性会单独记录在 `src/commands/doctor/shared/deprecation-compat.ts` 中。这些记录涵盖旧配置结构、安装账本布局以及修复垫片；即使运行时兼容路径已移除，它们也可能仍需保留。
|
||||
Doctor 修复和迁移兼容性会单独在 `src/commands/doctor/shared/deprecation-compat.ts` 中跟踪。这些记录涵盖旧的配置结构、安装台账布局以及修复垫片；即使运行时兼容路径已被移除，它们也可能仍需继续保留。
|
||||
|
||||
发布前的整体检查应同时检查这两个注册表。不要仅因为对应的运行时或配置兼容性记录已过期，就删除某个 Doctor 迁移；首先要确认是否仍存在需要该修复的受支持升级路径。还要在发布规划期间重新验证每条替代说明，因为随着提供商和渠道从核心中迁出，插件归属和配置范围可能会发生变化。
|
||||
发布清查应同时检查这两个注册表。不要仅仅因为对应的运行时或配置兼容性记录已过期，就删除某个 Doctor 迁移；首先要确认是否仍存在需要该修复的受支持升级路径。还要在发布规划期间重新验证每条替代说明，因为随着提供商和渠道迁出核心，插件归属和配置覆盖范围都可能发生变化。
|
||||
|
||||
## 插件检查器包
|
||||
|
||||
插件检查器应位于核心 OpenClaw 仓库之外，作为一个独立的软件包/仓库，并以有版本控制的兼容性契约和清单契约为基础。
|
||||
插件检查器应作为一个独立的包/仓库存在于 OpenClaw 核心仓库之外，并以带版本的兼容性契约和清单契约为基础。
|
||||
|
||||
首日 CLI 应为：
|
||||
|
||||
@ -47,56 +47,68 @@ openclaw-plugin-inspector ./my-plugin
|
||||
|
||||
它应输出：
|
||||
|
||||
- 清单/模式校验
|
||||
- 清单 / schema 校验
|
||||
- 正在检查的契约兼容版本
|
||||
- 安装/来源元数据检查
|
||||
- 安装 / 来源元数据检查
|
||||
- 冷路径导入检查
|
||||
- 弃用和兼容性警告
|
||||
|
||||
在 CI 注释中，请使用 `--json` 获取稳定的机器可读输出。OpenClaw 核心应暴露供检查器使用的契约和夹具，但不应从主 `openclaw` 包发布检查器二进制文件。
|
||||
在 CI 注释中使用 `--json` 可获得稳定的机器可读输出。OpenClaw 核心应暴露供检查器使用的契约和夹具，但不应从主 `openclaw` 包中发布检查器二进制文件。
|
||||
|
||||
## 弃用策略
|
||||
|
||||
OpenClaw 不应在引入替代方案的同一版本中移除已文档化的插件契约。
|
||||
OpenClaw 不应在引入某个已文档化插件契约替代方案的同一版本中移除该契约。
|
||||
|
||||
迁移顺序如下：
|
||||
|
||||
1. 添加新契约。
|
||||
2. 通过具名兼容适配器保留旧行为接通。
|
||||
3. 在插件作者可以采取行动时发出诊断信息或警告。
|
||||
2. 通过具名兼容性适配器继续保留旧行为。
|
||||
3. 当插件作者可以采取行动时，发出诊断或警告。
|
||||
4. 记录替代方案和时间线。
|
||||
5. 测试旧路径和新路径。
|
||||
6. 等待已宣布的迁移窗口结束。
|
||||
7. 仅在获得明确的破坏性版本发布批准后移除。
|
||||
5. 同时测试旧路径和新路径。
|
||||
6. 等待已公布的迁移窗口结束。
|
||||
7. 仅在获得明确的破坏性发布批准后才移除。
|
||||
|
||||
已弃用记录必须包含警告开始日期、替代方案、文档链接以及最终移除日期，且最终移除日期不得晚于警告开始后三个月。不要添加一个移除窗口无限期开放的已弃用兼容路径，除非维护者明确决定它是永久兼容，并将其标记为 `active`。
|
||||
已弃用记录必须包含警告开始日期、替代方案、文档链接，以及不晚于警告开始后三个月的最终移除日期。不要添加移除窗口无限期开放的已弃用兼容路径，除非维护者明确决定这是永久兼容性，并将其标记为 `active`。
|
||||
|
||||
## 当前兼容性领域
|
||||
## 当前兼容性范围
|
||||
|
||||
当前兼容性记录包括：
|
||||
当前的兼容性记录包括：
|
||||
|
||||
- 旧版宽泛 SDK 导入，例如 `openclaw/plugin-sdk/compat`
|
||||
- 旧版仅钩子插件形态以及 `before_agent_start`
|
||||
- 旧版 `activate(api)` 插件入口点，同时插件迁移到 `register(api)`
|
||||
- 旧版 SDK 别名，例如 `openclaw/extension-api`、`openclaw/plugin-sdk/channel-runtime`、`openclaw/plugin-sdk/command-auth` 状态构建器、`openclaw/plugin-sdk/test-utils`，以及 `ClawdbotConfig` / `OpenClawSchemaType` 类型别名
|
||||
- 旧版仅钩子插件结构和 `before_agent_start`
|
||||
- 旧版 `activate(api)` 插件入口点，同时插件正在迁移到 `register(api)`
|
||||
- 旧版 SDK 别名，例如 `openclaw/extension-api`、`openclaw/plugin-sdk/channel-runtime`、`openclaw/plugin-sdk/command-auth`
|
||||
状态构建器、`openclaw/plugin-sdk/test-utils`，以及 `ClawdbotConfig` /
|
||||
`OpenClawSchemaType` 类型别名
|
||||
- 内置插件允许列表和启用行为
|
||||
- 旧版提供商/渠道环境变量清单元数据
|
||||
- 旧版提供商插件钩子和类型别名，同时提供商迁移到显式的目录、认证、思考、重放和传输钩子
|
||||
- 旧版运行时别名，例如 `api.runtime.taskFlow`、`api.runtime.subagent.getSession` 和 `api.runtime.stt`
|
||||
- 旧版 memory 插件拆分注册，同时 memory 插件迁移到 `registerMemoryCapability`
|
||||
- 旧版渠道 SDK 辅助工具，用于原生消息模式、提及门控、入站信封格式化和审批能力嵌套
|
||||
- 旧版提供商 / 渠道环境变量清单元数据
|
||||
- 旧版提供商插件钩子和类型别名，同时提供商正在迁移到显式的 catalog、auth、thinking、replay 和 transport 钩子
|
||||
- 旧版运行时别名，例如 `api.runtime.taskFlow`、
|
||||
`api.runtime.subagent.getSession`、`api.runtime.stt`，以及已弃用的
|
||||
`api.runtime.config.loadConfig()` / `api.runtime.config.writeConfigFile(...)`
|
||||
- 旧版 memory 插件拆分注册，同时 memory 插件正在迁移到
|
||||
`registerMemoryCapability`
|
||||
- 旧版渠道 SDK 辅助工具，用于原生消息 schema、提及门控、入站信封格式化和审批能力嵌套
|
||||
- 正在由清单贡献归属替代的激活提示
|
||||
- `setup-api` 运行时回退，同时设置描述符迁移到冷路径 `setup.requiresRuntime: false` 元数据
|
||||
- 提供商 `discovery` 钩子，同时提供商目录钩子迁移到 `catalog.run(...)`
|
||||
- 渠道 `showConfigured` / `showInSetup` 元数据，同时渠道包迁移到 `openclaw.channel.exposure`
|
||||
- 旧版 runtime-policy 配置键，同时 Doctor 将操作员迁移到 `agentRuntime`
|
||||
- 生成的内置渠道配置元数据回退，同时以注册表优先的 `channelConfigs` 元数据正在落地
|
||||
- 持久化插件注册表禁用和安装迁移环境变量标记，同时修复流程将操作员迁移到 `openclaw plugins registry --refresh` 和 `openclaw doctor --fix`
|
||||
- 旧版由插件持有的 web search、web fetch 和 x_search 配置路径，同时 Doctor 将它们迁移到 `plugins.entries.<plugin>.config`
|
||||
- 旧版 `plugins.installs` 手写配置和内置插件加载路径别名，同时安装元数据迁移到状态管理的插件账本中
|
||||
- `setup-api` 运行时回退，同时 setup 描述符正在迁移到冷路径
|
||||
`setup.requiresRuntime: false` 元数据
|
||||
- 提供商 `discovery` 钩子，同时提供商 catalog 钩子正在迁移到
|
||||
`catalog.run(...)`
|
||||
- 渠道 `showConfigured` / `showInSetup` 元数据，同时渠道包正在迁移到
|
||||
`openclaw.channel.exposure`
|
||||
- 旧版 runtime-policy 配置键，同时 Doctor 正在将操作员迁移到
|
||||
`agentRuntime`
|
||||
- 生成的内置渠道配置元数据回退，同时注册表优先的
|
||||
`channelConfigs` 元数据正在落地
|
||||
- 持久化插件注册表禁用和安装迁移环境变量标志，同时修复流程正在将操作员迁移到 `openclaw plugins registry --refresh` 和
|
||||
`openclaw doctor --fix`
|
||||
- 旧版插件自有 web search、web fetch 和 x_search 配置路径，同时
|
||||
Doctor 正在将它们迁移到 `plugins.entries.<plugin>.config`
|
||||
- 旧版 `plugins.installs` 编写配置和内置插件加载路径别名，同时安装元数据正在迁移到由状态管理的插件台账中
|
||||
|
||||
新的插件代码应优先使用注册表和具体迁移指南中列出的替代方案。现有插件可以继续使用兼容路径，直到文档、诊断信息和发布说明宣布移除窗口。
|
||||
新的插件代码应优先使用注册表和具体迁移指南中列出的替代方案。现有插件可以继续使用兼容路径，直到文档、诊断信息和发布说明公布移除窗口。
|
||||
|
||||
## 发布说明
|
||||
|
||||
发布说明应包含即将到来的插件弃用项，并附上目标日期和迁移文档链接。必须在某个兼容路径转为 `removal-pending` 或 `removed` 之前发出该警告。
|
||||
发布说明应包含即将到来的插件弃用项、目标日期以及迁移文档链接。这个警告必须发生在某个兼容路径变为 `removal-pending` 或 `removed` 之前。
|
||||
|
||||
@ -2,85 +2,81 @@
|
||||
read_when:
|
||||
- 你看到了 `OPENCLAW_PLUGIN_SDK_COMPAT_DEPRECATED` 警告
|
||||
- 你看到了 `OPENCLAW_EXTENSION_API_DEPRECATED` 警告
|
||||
- 你在 OpenClaw 2026.4.25 之前使用过 `api.registerEmbeddedExtensionFactory`
|
||||
- 你正在将插件更新到现代插件架构
|
||||
- 你在维护一个外部 OpenClaw 插件
|
||||
- 你在 OpenClaw 2026.4.25 之前使用了 `api.registerEmbeddedExtensionFactory`
|
||||
- 你正在将插件更新为现代插件架构
|
||||
- 你维护一个外部 OpenClaw 插件
|
||||
sidebarTitle: Migrate to SDK
|
||||
summary: 从旧版向后兼容层迁移到现代插件 SDK
|
||||
title: 插件 SDK 迁移
|
||||
x-i18n:
|
||||
generated_at: "2026-04-27T12:54:53Z"
|
||||
generated_at: "2026-04-27T13:31:49Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 40dd590e9a9a2a340da9b6ecba5dd471713552a214aa7fd24970db2b47a4a04c
|
||||
source_hash: 8b012d99b9d918e2f39fd21f490b5229b4e4a928ef4196d5b1bbf2f8b0cc55b8
|
||||
source_path: plugins/sdk-migration.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
OpenClaw 已从宽泛的向后兼容层迁移到具有聚焦且文档化导入路径的现代插件架构。如果你的插件构建于新架构之前，本指南将帮助你完成迁移。
|
||||
OpenClaw 已从宽泛的向后兼容层迁移到现代插件架构，后者使用聚焦且有文档记录的导入路径。如果你的插件构建于新架构之前，本指南将帮助你完成迁移。
|
||||
|
||||
## 正在发生什么变化
|
||||
## 正在发生哪些变化
|
||||
|
||||
旧的插件系统提供了两个开放面很大的接口，使插件能够从单一入口点导入所需的任何内容：
|
||||
旧版插件系统提供了两个开放范围很大的表面，使插件能够从单一入口点导入所需的任何内容：
|
||||
|
||||
- **`openclaw/plugin-sdk/compat`** —— 一个会重新导出数十个辅助工具的单一导入入口。它的引入是为了在新的插件架构构建期间，让较旧的基于 hook 的插件继续工作。
|
||||
- **`openclaw/extension-api`** —— 一个桥接层，让插件可以直接访问主机侧辅助工具，例如嵌入式智能体运行器。
|
||||
- **`api.registerEmbeddedExtensionFactory(...)`** —— 一个已移除的、仅适用于 Pi 的内置扩展 hook，它过去可以观察诸如 `tool_result` 这样的嵌入式运行器事件。
|
||||
- **`openclaw/plugin-sdk/compat`** — 一个单一导入，重新导出了数十个辅助工具。它的引入是为了在构建新插件架构期间，让旧的基于钩子的插件继续工作。
|
||||
- **`openclaw/extension-api`** — 一个桥接层，使插件可以直接访问宿主侧辅助工具，例如嵌入式智能体运行器。
|
||||
- **`api.registerEmbeddedExtensionFactory(...)`** — 一个已移除的、仅限 Pi 的内置扩展钩子，可观察诸如 `tool_result` 之类的嵌入式运行器事件。
|
||||
|
||||
这些宽泛的导入接口现在都已**弃用**。它们在运行时仍然可用，但新插件不得再使用它们，现有插件也应在下一个主版本移除它们之前完成迁移。仅适用于 Pi 的嵌入式扩展工厂注册 API 已被移除；请改用工具结果中间件。
|
||||
这些宽泛的导入表面现已被**弃用**。它们在运行时仍然可用，但新插件不得再使用它们，现有插件应在下一个主要版本移除它们之前完成迁移。仅限 Pi 的嵌入式扩展工厂注册 API 已被移除；请改用工具结果中间件。
|
||||
|
||||
OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释已文档化的插件行为。破坏性契约变更必须先经过兼容适配器、诊断、文档和弃用窗口。此规则适用于 SDK 导入、manifest 字段、设置 API、hooks 和运行时注册行为。
|
||||
OpenClaw 不会在引入替代方案的同一变更中，移除或重新解释已有文档记录的插件行为。破坏性契约变更必须先经过兼容适配器、诊断信息、文档以及弃用窗口。这同样适用于 SDK 导入、清单字段、设置 API、钩子和运行时注册行为。
|
||||
|
||||
<Warning>
|
||||
向后兼容层将在未来的某个主版本中移除。
|
||||
仍从这些接口导入的插件到时将会失效。
|
||||
仅适用于 Pi 的嵌入式扩展工厂注册现已不再加载。
|
||||
向后兼容层将在未来的主要版本中移除。届时，仍从这些表面导入的插件将会失效。
|
||||
仅限 Pi 的嵌入式扩展工厂注册已不再加载。
|
||||
</Warning>
|
||||
|
||||
## 为什么会有这项变化
|
||||
## 为什么会有这个变化
|
||||
|
||||
旧方法带来了若干问题：
|
||||
旧方法会导致一些问题：
|
||||
|
||||
- **启动缓慢** —— 导入一个辅助工具会连带加载数十个无关模块
|
||||
- **循环依赖** —— 宽泛的重新导出使创建导入环路变得很容易
|
||||
- **API 界面不清晰** —— 无法分辨哪些导出是稳定的，哪些是内部实现
|
||||
- **启动缓慢** — 导入一个辅助工具会加载数十个无关模块
|
||||
- **循环依赖** — 宽泛的重新导出使导入循环更容易出现
|
||||
- **API 表面不清晰** — 无法分辨哪些导出是稳定的，哪些是内部实现
|
||||
|
||||
现代插件 SDK 解决了这些问题：每个导入路径（`openclaw/plugin-sdk/\<subpath\>`）都是一个小型、自包含的模块，具有明确用途和文档化契约。
|
||||
现代插件 SDK 解决了这些问题：每个导入路径（`openclaw/plugin-sdk/\<subpath\>`）都是一个小型、自包含模块，具有清晰用途和有文档记录的契约。
|
||||
|
||||
面向内置渠道的旧版 provider 便捷接口也已移除。
|
||||
带有渠道品牌的辅助接口曾是私有 mono-repo 捷径，而不是稳定的插件契约。请改用更窄的通用 SDK 子路径。在内置插件工作区内，应将 provider 自有的辅助工具保留在该插件自己的 `api.ts` 或 `runtime-api.ts` 中。
|
||||
针对内置渠道的旧版 provider 便捷接缝也已移除。
|
||||
带有渠道品牌的辅助工具接缝是私有 mono-repo 快捷方式，而不是稳定的插件契约。请改用狭义的通用 SDK 子路径。在内置插件工作区中，请将 provider 自有辅助工具保留在该插件自己的 `api.ts` 或 `runtime-api.ts` 中。
|
||||
|
||||
当前内置 provider 示例：
|
||||
|
||||
- Anthropic 将 Claude 特定的流式辅助工具保留在自己的 `api.ts` /
|
||||
`contract-api.ts` 接口中
|
||||
- OpenAI 将 provider builder、默认模型辅助工具和 realtime provider
|
||||
builder 保留在自己的 `api.ts` 中
|
||||
- OpenRouter 将 provider builder 以及新手引导/配置辅助工具保留在自己的
|
||||
`api.ts` 中
|
||||
- Anthropic 将 Claude 专用的流式辅助工具保留在它自己的 `api.ts` / `contract-api.ts` 接缝中
|
||||
- OpenAI 将 provider 构建器、默认模型辅助工具和实时 provider 构建器保留在它自己的 `api.ts` 中
|
||||
- OpenRouter 将 provider 构建器以及新手引导 / 配置辅助工具保留在它自己的 `api.ts` 中
|
||||
|
||||
## 兼容性策略
|
||||
|
||||
对于外部插件，兼容性工作遵循以下顺序：
|
||||
|
||||
1. 添加新契约
|
||||
2. 通过兼容适配器保留旧行为
|
||||
3. 发出诊断或警告，明确指出旧路径及其替代方案
|
||||
4. 在测试中覆盖两条路径
|
||||
1. 添加新的契约
|
||||
2. 通过兼容适配器保持旧行为继续连通
|
||||
3. 发出点明旧路径和替代方案的诊断或警告
|
||||
4. 在测试中覆盖这两条路径
|
||||
5. 记录弃用和迁移路径
|
||||
6. 仅在公布的迁移窗口结束后移除，通常是在主版本中
|
||||
6. 仅在已宣布的迁移窗口结束后移除，通常是在主要版本中
|
||||
|
||||
如果某个 manifest 字段仍然被接受，插件作者就可以继续使用它，直到文档和诊断另行说明。新代码应优先采用文档化的替代方案，但现有插件不应在普通的小版本发布中失效。
|
||||
如果某个清单字段仍被接受，插件作者就可以继续使用它，直到文档和诊断信息另有说明。新代码应优先使用有文档记录的替代方案，但现有插件不应在普通次要版本发布期间失效。
|
||||
|
||||
## 如何迁移
|
||||
|
||||
<Steps>
|
||||
<Step title="迁移运行时配置加载/写入辅助工具">
|
||||
<Step title="迁移运行时配置加载 / 写入辅助工具">
|
||||
内置插件应停止直接调用
|
||||
`api.runtime.config.loadConfig()` 和
|
||||
`api.runtime.config.writeConfigFile(...)`。应优先使用已传入当前调用路径中的配置。需要当前进程快照的长生命周期处理器可使用 `api.runtime.config.current()`。长生命周期的智能体工具应在 `execute` 中使用工具上下文的 `ctx.getRuntimeConfig()`，这样即使工具创建于配置写入之前，也仍能看到刷新的运行时配置。
|
||||
`api.runtime.config.writeConfigFile(...)`。优先使用已传入当前活动调用路径的配置。需要当前进程快照的长生命周期处理器可以使用 `api.runtime.config.current()`。长生命周期智能体工具应在 `execute` 中使用工具上下文的 `ctx.getRuntimeConfig()`，这样在配置写入之前创建的工具仍然可以看到刷新后的运行时配置。
|
||||
|
||||
配置写入必须通过事务性辅助工具完成，并选择写入后的策略：
|
||||
配置写入必须通过事务型辅助工具完成，并选择写入后的策略：
|
||||
|
||||
```typescript
|
||||
await api.runtime.config.mutateConfigFile({
|
||||
@ -91,21 +87,23 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释
|
||||
});
|
||||
```
|
||||
|
||||
当调用方明确知道变更需要一次干净的 Gateway 网关重启时，请使用
|
||||
`afterWrite: { mode: "restart", reason: "..." }`；只有当调用方自行负责后续处理并且有意抑制重载规划器时，才使用
|
||||
当调用方知道该更改需要一次干净的 Gateway 网关重启时，请使用
|
||||
`afterWrite: { mode: "restart", reason: "..." }`；只有当调用方自行负责后续操作并且有意抑制重载规划器时，才使用
|
||||
`afterWrite: { mode: "none", reason: "..." }`。
|
||||
变更结果会包含一个带类型的 `followUp` 摘要，用于测试和日志记录；Gateway 网关仍负责实际执行或调度重启。
|
||||
`loadConfig` 和 `writeConfigFile` 在迁移窗口期间仍作为已弃用的兼容辅助工具保留给外部插件使用，并会在调用时发出一次警告。
|
||||
内置插件和仓库运行时代码会受到 `pnpm check:deprecated-internal-config-api` 中扫描防护的约束：新的生产插件用法会直接失败，直接配置写入会失败，Gateway 网关服务器方法必须使用请求运行时快照，而长生命周期运行时模块不得存在任何环境式 `loadConfig()` 调用。
|
||||
变更结果会包含一个带类型的 `followUp` 摘要，用于测试和日志；Gateway 网关仍负责执行或调度重启。
|
||||
`loadConfig` 和 `writeConfigFile` 在迁移窗口期间仍作为外部插件的已弃用兼容辅助工具保留，并会以 `runtime-config-load-write` 兼容性代码发出一次警告。内置插件和仓库运行时代码受
|
||||
`pnpm check:deprecated-internal-config-api` 和
|
||||
`pnpm check:no-runtime-action-load-config`
|
||||
中的扫描器护栏保护：新的生产插件用法会直接失败，直接配置写入会失败，Gateway 网关服务器方法必须使用请求运行时快照，运行时渠道发送 / 动作 / 客户端辅助工具必须从其边界接收配置，而长生命周期运行时模块不允许存在任何环境式 `loadConfig()` 调用。
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="将 Pi 工具结果扩展迁移到中间件">
|
||||
内置插件必须将仅适用于 Pi 的
|
||||
`api.registerEmbeddedExtensionFactory(...)` 工具结果处理器替换为运行时无关的中间件。
|
||||
内置插件必须将仅限 Pi 的
|
||||
`api.registerEmbeddedExtensionFactory(...)` 工具结果处理器替换为与运行时无关的中间件。
|
||||
|
||||
```typescript
|
||||
// Pi 和 Codex 运行时动态工具
|
||||
// Pi and Codex runtime dynamic tools
|
||||
api.registerAgentToolResultMiddleware(async (event) => {
|
||||
return compactToolResult(event);
|
||||
}, {
|
||||
@ -113,7 +111,7 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释
|
||||
});
|
||||
```
|
||||
|
||||
同时更新插件 manifest：
|
||||
同时更新插件清单：
|
||||
|
||||
```json
|
||||
{
|
||||
@ -123,40 +121,33 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释
|
||||
}
|
||||
```
|
||||
|
||||
外部插件不能注册工具结果中间件，因为这会在模型看到结果之前重写高信任度的工具输出。
|
||||
外部插件不能注册工具结果中间件，因为它可以在模型看到高信任工具输出之前对其进行重写。
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="将原生 approval 处理器迁移到 capability facts">
|
||||
支持 approval 的渠道插件现在通过
|
||||
`approvalCapability.nativeRuntime` 加上共享运行时上下文注册表来公开原生 approval 行为。
|
||||
<Step title="将原生审批处理器迁移到能力事实">
|
||||
具备审批能力的渠道插件现在通过
|
||||
`approvalCapability.nativeRuntime` 加上共享运行时上下文注册表来公开原生审批行为。
|
||||
|
||||
关键变化：
|
||||
|
||||
- 用 `approvalCapability.nativeRuntime` 替换
|
||||
`approvalCapability.handler.loadRuntime(...)`
|
||||
- 将 approval 特有的认证/交付从旧版 `plugin.auth` /
|
||||
`plugin.approvals` 线路中迁出，改放到 `approvalCapability`
|
||||
- `ChannelPlugin.approvals` 已从公共渠道插件契约中移除；
|
||||
请将 delivery/native/render 字段迁移到 `approvalCapability`
|
||||
- `plugin.auth` 仅保留给渠道登录/登出流程；其中的 approval
|
||||
认证 hooks 不再被核心读取
|
||||
- 将 `approvalCapability.handler.loadRuntime(...)` 替换为
|
||||
`approvalCapability.nativeRuntime`
|
||||
- 将审批专用的认证 / 传递从旧版 `plugin.auth` /
|
||||
`plugin.approvals` 接线迁移到 `approvalCapability`
|
||||
- `ChannelPlugin.approvals` 已从公共渠道插件契约中移除；请将 delivery / native / render 字段迁移到 `approvalCapability`
|
||||
- `plugin.auth` 仅保留用于渠道登录 / 登出流程；其中的审批认证钩子不再被核心读取
|
||||
- 通过 `openclaw/plugin-sdk/channel-runtime-context`
|
||||
注册由渠道持有的运行时对象，例如客户端、token 或 Bolt
|
||||
应用
|
||||
- 不要从原生 approval 处理器发送由插件自有的改道通知；
|
||||
核心现在会根据实际交付结果自行处理“已路由到其他位置”的通知
|
||||
- 当把 `channelRuntime` 传入 `createChannelManager(...)` 时，请提供真实的 `createPluginRuntime().channel` 接口。部分 stub 会被拒绝。
|
||||
注册渠道自有的运行时对象，例如客户端、令牌或 Bolt 应用
|
||||
- 不要从原生审批处理器发送插件自有的重路由通知；核心现在根据实际传递结果负责“已路由到其他地方”的通知
|
||||
- 将 `channelRuntime` 传入 `createChannelManager(...)` 时，请提供真实的 `createPluginRuntime().channel` 表面。部分桩实现会被拒绝。
|
||||
|
||||
参见 `/plugins/sdk-channel-plugins` 了解当前的 approval capability
|
||||
布局。
|
||||
当前审批能力布局请参见 `/plugins/sdk-channel-plugins`。
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="审查 Windows wrapper fallback 行为">
|
||||
如果你的插件使用 `openclaw/plugin-sdk/windows-spawn`，现在未解析的 Windows
|
||||
`.cmd`/`.bat` wrapper 会默认失败即关闭，除非你显式传入
|
||||
`allowShellFallback: true`。
|
||||
<Step title="审查 Windows 包装器回退行为">
|
||||
如果你的插件使用 `openclaw/plugin-sdk/windows-spawn`，现在对于无法解析的 Windows `.cmd`/`.bat` 包装器会默认失败关闭，除非你显式传入 `allowShellFallback: true`。
|
||||
|
||||
```typescript
|
||||
// Before
|
||||
@ -165,18 +156,18 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释
|
||||
// After
|
||||
const program = applyWindowsSpawnProgramPolicy({
|
||||
candidate,
|
||||
// 仅对那些有意接受 shell 中介 fallback 的可信兼容调用方设置此项。
|
||||
// Only set this for trusted compatibility callers that intentionally
|
||||
// accept shell-mediated fallback.
|
||||
allowShellFallback: true,
|
||||
});
|
||||
```
|
||||
|
||||
如果你的调用方并不有意依赖 shell fallback，就不要设置
|
||||
`allowShellFallback`，而应改为处理抛出的错误。
|
||||
如果你的调用方并非有意依赖 shell 回退，请不要设置 `allowShellFallback`，而应改为处理抛出的错误。
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="查找已弃用的导入">
|
||||
在你的插件中搜索来自以下任一已弃用接口的导入：
|
||||
在你的插件中搜索是否从任一已弃用表面导入：
|
||||
|
||||
```bash
|
||||
grep -r "plugin-sdk/compat" my-plugin/
|
||||
@ -186,34 +177,34 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释
|
||||
</Step>
|
||||
|
||||
<Step title="替换为聚焦导入">
|
||||
旧接口中的每个导出都映射到一个明确的现代导入路径：
|
||||
旧表面中的每个导出都映射到一个特定的现代导入路径：
|
||||
|
||||
```typescript
|
||||
// Before（已弃用的向后兼容层）
|
||||
// Before (deprecated backwards-compatibility layer)
|
||||
import {
|
||||
createChannelReplyPipeline,
|
||||
createPluginRuntimeStore,
|
||||
resolveControlCommandGate,
|
||||
} from "openclaw/plugin-sdk/compat";
|
||||
|
||||
// After（现代聚焦导入）
|
||||
// After (modern focused imports)
|
||||
import { createChannelReplyPipeline } from "openclaw/plugin-sdk/channel-reply-pipeline";
|
||||
import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store";
|
||||
import { resolveControlCommandGate } from "openclaw/plugin-sdk/command-auth";
|
||||
```
|
||||
|
||||
对于主机侧辅助工具，请使用注入的插件运行时，而不是直接导入：
|
||||
对于宿主侧辅助工具，请使用注入的插件运行时，而不是直接导入：
|
||||
|
||||
```typescript
|
||||
// Before（已弃用的 extension-api 桥接）
|
||||
// Before (deprecated extension-api bridge)
|
||||
import { runEmbeddedPiAgent } from "openclaw/extension-api";
|
||||
const result = await runEmbeddedPiAgent({ sessionId, prompt });
|
||||
|
||||
// After（注入式运行时）
|
||||
// After (injected runtime)
|
||||
const result = await api.runtime.agent.runEmbeddedPiAgent({ sessionId, prompt });
|
||||
```
|
||||
|
||||
其他旧版桥接辅助工具也遵循同样的模式：
|
||||
其他旧版桥接辅助工具也适用同样的模式：
|
||||
|
||||
| 旧导入 | 现代等价项 |
|
||||
| --- | --- |
|
||||
@ -237,177 +228,179 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释
|
||||
|
||||
## 导入路径参考
|
||||
|
||||
<Accordion title="常用导入路径表">
|
||||
<Accordion title="常见导入路径表">
|
||||
| 导入路径 | 用途 | 关键导出 |
|
||||
| --- | --- | --- |
|
||||
| `plugin-sdk/plugin-entry` | 规范的插件入口辅助工具 | `definePluginEntry` |
|
||||
| `plugin-sdk/core` | 面向渠道入口定义/builders 的旧版聚合重新导出 | `defineChannelPluginEntry`, `createChatChannelPlugin` |
|
||||
| `plugin-sdk/config-schema` | 根配置 schema 导出 | `OpenClawSchema` |
|
||||
| `plugin-sdk/provider-entry` | 单提供商入口辅助工具 | `defineSingleProviderPluginEntry` |
|
||||
| `plugin-sdk/channel-core` | 聚焦的渠道入口定义和 builders | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` |
|
||||
| `plugin-sdk/setup` | 共享设置向导辅助工具 | Allowlist 提示、设置 Status builders |
|
||||
| `plugin-sdk/setup-runtime` | 设置阶段运行时辅助工具 | 可安全导入的设置补丁适配器、lookup-note 辅助工具、`promptResolvedAllowFrom`、`splitSetupEntries`、委托设置代理 |
|
||||
| `plugin-sdk/plugin-entry` | 规范插件入口辅助工具 | `definePluginEntry` |
|
||||
| `plugin-sdk/core` | 用于渠道入口定义 / 构建器的旧版总入口重新导出 | `defineChannelPluginEntry`, `createChatChannelPlugin` |
|
||||
| `plugin-sdk/config-schema` | 根配置模式导出 | `OpenClawSchema` |
|
||||
| `plugin-sdk/provider-entry` | 单一 provider 入口辅助工具 | `defineSingleProviderPluginEntry` |
|
||||
| `plugin-sdk/channel-core` | 聚焦的渠道入口定义和构建器 | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` |
|
||||
| `plugin-sdk/setup` | 共享设置向导辅助工具 | Allowlist 提示、设置状态构建器 |
|
||||
| `plugin-sdk/setup-runtime` | 设置时运行时辅助工具 | 可安全导入的设置补丁适配器、lookup-note 辅助工具、`promptResolvedAllowFrom`、`splitSetupEntries`、委托设置代理 |
|
||||
| `plugin-sdk/setup-adapter-runtime` | 设置适配器辅助工具 | `createEnvPatchedAccountSetupAdapter` |
|
||||
| `plugin-sdk/setup-tools` | 设置工具辅助工具 | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` |
|
||||
| `plugin-sdk/account-core` | 多账户辅助工具 | 账户列表/配置/action-gate 辅助工具 |
|
||||
| `plugin-sdk/account-core` | 多账户辅助工具 | 账户列表 / 配置 / 动作门控辅助工具 |
|
||||
| `plugin-sdk/account-id` | account-id 辅助工具 | `DEFAULT_ACCOUNT_ID`、account-id 规范化 |
|
||||
| `plugin-sdk/account-resolution` | 账户查找辅助工具 | 账户查找 + 默认回退辅助工具 |
|
||||
| `plugin-sdk/account-helpers` | 窄范围账户辅助工具 | 账户列表/account-action 辅助工具 |
|
||||
| `plugin-sdk/channel-setup` | 设置向导适配器 | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`，以及 `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` |
|
||||
| `plugin-sdk/account-helpers` | 狭义账户辅助工具 | 账户列表 / 账户动作辅助工具 |
|
||||
| `plugin-sdk/channel-setup` | 设置向导适配器 | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`，以及 `DEFAULT_ACCOUNT_ID`、`createTopLevelChannelDmPolicy`、`setSetupChannelEnabled`、`splitSetupEntries` |
|
||||
| `plugin-sdk/channel-pairing` | 私信配对原语 | `createChannelPairingController` |
|
||||
| `plugin-sdk/channel-reply-pipeline` | 回复前缀 + 输入中 wiring | `createChannelReplyPipeline` |
|
||||
| `plugin-sdk/channel-reply-pipeline` | 回复前缀 + 正在输入接线 | `createChannelReplyPipeline` |
|
||||
| `plugin-sdk/channel-config-helpers` | 配置适配器工厂 | `createHybridChannelConfigAdapter` |
|
||||
| `plugin-sdk/channel-config-schema` | 配置 schema builders | 共享渠道配置 schema 原语以及通用 builder |
|
||||
| `plugin-sdk/channel-config-schema-legacy` | 已弃用的内置配置 schema | 仅用于内置兼容；新插件必须定义插件本地 schema |
|
||||
| `plugin-sdk/telegram-command-config` | Telegram 命令配置辅助工具 | 命令名规范化、描述裁剪、重复/冲突校验 |
|
||||
| `plugin-sdk/channel-policy` | 群组/私信策略解析 | `resolveChannelGroupRequireMention` |
|
||||
| `plugin-sdk/channel-lifecycle` | 账户 Status 和草稿流生命周期辅助工具 | `createAccountStatusSink`、草稿预览最终化辅助工具 |
|
||||
| `plugin-sdk/inbound-envelope` | 入站 envelope 辅助工具 | 共享路由 + envelope builder 辅助工具 |
|
||||
| `plugin-sdk/inbound-reply-dispatch` | 入站回复辅助工具 | 共享 record-and-dispatch 辅助工具 |
|
||||
| `plugin-sdk/messaging-targets` | 消息目标解析 | 目标解析/匹配辅助工具 |
|
||||
| `plugin-sdk/channel-config-schema` | 配置模式构建器 | 共享渠道配置模式原语和仅通用构建器 |
|
||||
| `plugin-sdk/channel-config-schema-legacy` | 已弃用的内置配置模式 | 仅用于内置兼容；新插件必须定义插件本地模式 |
|
||||
| `plugin-sdk/telegram-command-config` | Telegram 命令配置辅助工具 | 命令名称规范化、描述裁剪、重复 / 冲突校验 |
|
||||
| `plugin-sdk/channel-policy` | 群组 / 私信策略解析 | `resolveChannelGroupRequireMention` |
|
||||
| `plugin-sdk/channel-lifecycle` | 账户状态和草稿流生命周期辅助工具 | `createAccountStatusSink`、草稿预览完成辅助工具 |
|
||||
| `plugin-sdk/inbound-envelope` | 入站 envelope 辅助工具 | 共享 route + envelope 构建器辅助工具 |
|
||||
| `plugin-sdk/inbound-reply-dispatch` | 入站回复辅助工具 | 共享记录并分发辅助工具 |
|
||||
| `plugin-sdk/messaging-targets` | 消息目标解析 | 目标解析 / 匹配辅助工具 |
|
||||
| `plugin-sdk/outbound-media` | 出站媒体辅助工具 | 共享出站媒体加载 |
|
||||
| `plugin-sdk/outbound-send-deps` | 出站发送依赖辅助工具 | 无需导入完整出站运行时的轻量 `resolveOutboundSendDep` 查找 |
|
||||
| `plugin-sdk/outbound-runtime` | 出站运行时辅助工具 | 出站交付、identity/send delegate、会话、格式化和负载规划辅助工具 |
|
||||
| `plugin-sdk/outbound-send-deps` | 出站发送依赖辅助工具 | 轻量级 `resolveOutboundSendDep` 查找，无需导入完整出站运行时 |
|
||||
| `plugin-sdk/outbound-runtime` | 出站运行时辅助工具 | 出站投递、身份 / 发送委托、会话、格式化和载荷规划辅助工具 |
|
||||
| `plugin-sdk/thread-bindings-runtime` | 线程绑定辅助工具 | 线程绑定生命周期和适配器辅助工具 |
|
||||
| `plugin-sdk/agent-media-payload` | 旧版媒体负载辅助工具 | 面向旧字段布局的智能体媒体负载 builder |
|
||||
| `plugin-sdk/channel-runtime` | 已弃用的兼容 shim | 仅旧版渠道运行时工具 |
|
||||
| `plugin-sdk/agent-media-payload` | 旧版媒体载荷辅助工具 | 用于旧版字段布局的智能体媒体载荷构建器 |
|
||||
| `plugin-sdk/channel-runtime` | 已弃用的兼容性 shim | 仅旧版渠道运行时工具 |
|
||||
| `plugin-sdk/channel-send-result` | 发送结果类型 | 回复结果类型 |
|
||||
| `plugin-sdk/runtime-store` | 持久化插件存储 | `createPluginRuntimeStore` |
|
||||
| `plugin-sdk/runtime` | 宽范围运行时辅助工具 | 运行时/日志/备份/插件安装辅助工具 |
|
||||
| `plugin-sdk/runtime-env` | 窄范围运行时环境辅助工具 | logger/运行时环境、超时、重试和退避辅助工具 |
|
||||
| `plugin-sdk/plugin-runtime` | 共享插件运行时辅助工具 | 插件命令/hooks/http/交互辅助工具 |
|
||||
| `plugin-sdk/hook-runtime` | hook 管线辅助工具 | 共享 webhook/内部 hook 管线辅助工具 |
|
||||
| `plugin-sdk/runtime` | 宽泛运行时辅助工具 | 运行时 / 日志 / 备份 / 插件安装辅助工具 |
|
||||
| `plugin-sdk/runtime-env` | 狭义运行时环境辅助工具 | logger / 运行时环境、超时、重试和退避辅助工具 |
|
||||
| `plugin-sdk/plugin-runtime` | 共享插件运行时辅助工具 | 插件命令 / 钩子 / http / 交互式辅助工具 |
|
||||
| `plugin-sdk/hook-runtime` | 钩子流水线辅助工具 | 共享 webhook / 内部钩子流水线辅助工具 |
|
||||
| `plugin-sdk/lazy-runtime` | 惰性运行时辅助工具 | `createLazyRuntimeModule`, `createLazyRuntimeMethod`, `createLazyRuntimeMethodBinder`, `createLazyRuntimeNamedExport`, `createLazyRuntimeSurface` |
|
||||
| `plugin-sdk/process-runtime` | 进程辅助工具 | 共享 exec 辅助工具 |
|
||||
| `plugin-sdk/cli-runtime` | CLI 运行时辅助工具 | 命令格式化、等待、版本辅助工具 |
|
||||
| `plugin-sdk/gateway-runtime` | Gateway 网关辅助工具 | Gateway 网关客户端和渠道 Status 补丁辅助工具 |
|
||||
| `plugin-sdk/config-runtime` | 配置辅助工具 | 配置加载/写入辅助工具 |
|
||||
| `plugin-sdk/telegram-command-config` | Telegram 命令辅助工具 | 当内置 Telegram 契约接口不可用时，提供稳定 fallback 的 Telegram 命令校验辅助工具 |
|
||||
| `plugin-sdk/approval-runtime` | approval 提示辅助工具 | exec/插件 approval 负载、approval capability/profile 辅助工具、原生 approval 路由/运行时辅助工具，以及结构化 approval 显示路径格式化 |
|
||||
| `plugin-sdk/approval-auth-runtime` | approval 认证辅助工具 | approver 解析、同聊天 action 认证 |
|
||||
| `plugin-sdk/approval-client-runtime` | approval 客户端辅助工具 | 原生 exec approval profile/filter 辅助工具 |
|
||||
| `plugin-sdk/approval-delivery-runtime` | approval 交付辅助工具 | 原生 approval capability/delivery 适配器 |
|
||||
| `plugin-sdk/approval-gateway-runtime` | approval Gateway 网关辅助工具 | 共享 approval Gateway 网关解析辅助工具 |
|
||||
| `plugin-sdk/approval-handler-adapter-runtime` | approval 适配器辅助工具 | 面向热渠道入口点的轻量原生 approval 适配器加载辅助工具 |
|
||||
| `plugin-sdk/approval-handler-runtime` | approval 处理器辅助工具 | 更宽范围的 approval 处理器运行时辅助工具；若较窄的 adapter/gateway 接口已足够，则优先使用它们 |
|
||||
| `plugin-sdk/approval-native-runtime` | approval 目标辅助工具 | 原生 approval 目标/账户绑定辅助工具 |
|
||||
| `plugin-sdk/approval-reply-runtime` | approval 回复辅助工具 | exec/插件 approval 回复负载辅助工具 |
|
||||
| `plugin-sdk/channel-runtime-context` | 渠道运行时上下文辅助工具 | 通用的渠道运行时上下文 register/get/watch 辅助工具 |
|
||||
| `plugin-sdk/security-runtime` | 安全辅助工具 | 共享信任、私信门控、外部内容和 secret 收集辅助工具 |
|
||||
| `plugin-sdk/gateway-runtime` | Gateway 网关辅助工具 | Gateway 网关客户端和渠道状态补丁辅助工具 |
|
||||
| `plugin-sdk/config-runtime` | 配置辅助工具 | 配置加载 / 写入辅助工具 |
|
||||
| `plugin-sdk/telegram-command-config` | Telegram 命令辅助工具 | 当内置 Telegram 契约表面不可用时，提供回退稳定的 Telegram 命令校验辅助工具 |
|
||||
| `plugin-sdk/approval-runtime` | 审批提示辅助工具 | exec / 插件审批载荷、审批能力 / 配置文件辅助工具、原生审批路由 / 运行时辅助工具，以及结构化审批显示路径格式化 |
|
||||
| `plugin-sdk/approval-auth-runtime` | 审批认证辅助工具 | 审批人解析、同聊天动作认证 |
|
||||
| `plugin-sdk/approval-client-runtime` | 审批客户端辅助工具 | 原生 exec 审批配置文件 / 过滤器辅助工具 |
|
||||
| `plugin-sdk/approval-delivery-runtime` | 审批投递辅助工具 | 原生审批能力 / 投递适配器 |
|
||||
| `plugin-sdk/approval-gateway-runtime` | 审批 Gateway 网关辅助工具 | 共享审批 Gateway 网关解析辅助工具 |
|
||||
| `plugin-sdk/approval-handler-adapter-runtime` | 审批适配器辅助工具 | 用于热渠道入口点的轻量级原生审批适配器加载辅助工具 |
|
||||
| `plugin-sdk/approval-handler-runtime` | 审批处理器辅助工具 | 更宽泛的审批处理器运行时辅助工具；如果狭义的适配器 / Gateway 网关接缝已足够，则优先使用后者 |
|
||||
| `plugin-sdk/approval-native-runtime` | 审批目标辅助工具 | 原生审批目标 / 账户绑定辅助工具 |
|
||||
| `plugin-sdk/approval-reply-runtime` | 审批回复辅助工具 | exec / 插件审批回复载荷辅助工具 |
|
||||
| `plugin-sdk/channel-runtime-context` | 渠道运行时上下文辅助工具 | 通用渠道运行时上下文 register / get / watch 辅助工具 |
|
||||
| `plugin-sdk/security-runtime` | 安全辅助工具 | 共享信任、私信门控、外部内容和密钥收集辅助工具 |
|
||||
| `plugin-sdk/ssrf-policy` | SSRF 策略辅助工具 | 主机 allowlist 和私有网络策略辅助工具 |
|
||||
| `plugin-sdk/ssrf-runtime` | SSRF 运行时辅助工具 | pinned-dispatcher、受保护 fetch、SSRF 策略辅助工具 |
|
||||
| `plugin-sdk/ssrf-runtime` | SSRF 运行时辅助工具 | 固定 dispatcher、受保护 fetch、SSRF 策略辅助工具 |
|
||||
| `plugin-sdk/collection-runtime` | 有界缓存辅助工具 | `pruneMapToMaxSize` |
|
||||
| `plugin-sdk/diagnostic-runtime` | 诊断门控辅助工具 | `isDiagnosticFlagEnabled`, `isDiagnosticsEnabled` |
|
||||
| `plugin-sdk/error-runtime` | 错误格式化辅助工具 | `formatUncaughtError`, `isApprovalNotFoundError`, 错误图辅助工具 |
|
||||
| `plugin-sdk/fetch-runtime` | 包装过的 fetch/代理辅助工具 | `resolveFetch`、代理辅助工具 |
|
||||
| `plugin-sdk/error-runtime` | 错误格式化辅助工具 | `formatUncaughtError`, `isApprovalNotFoundError`、错误图辅助工具 |
|
||||
| `plugin-sdk/fetch-runtime` | 封装的 fetch / 代理辅助工具 | `resolveFetch`、代理辅助工具 |
|
||||
| `plugin-sdk/host-runtime` | 主机规范化辅助工具 | `normalizeHostname`, `normalizeScpRemoteHost` |
|
||||
| `plugin-sdk/retry-runtime` | 重试辅助工具 | `RetryConfig`, `retryAsync`, 策略运行器 |
|
||||
| `plugin-sdk/allow-from` | Allowlist 格式化 | `formatAllowFromLowercase` |
|
||||
| `plugin-sdk/allowlist-resolution` | Allowlist 输入映射 | `mapAllowlistResolutionInputs` |
|
||||
| `plugin-sdk/command-auth` | 命令门控和命令接口辅助工具 | `resolveControlCommandGate`、发送者授权辅助工具、命令注册表辅助工具，包括动态参数菜单格式化 |
|
||||
| `plugin-sdk/command-status` | 命令 Status/帮助渲染器 | `buildCommandsMessage`, `buildCommandsMessagePaginated`, `buildHelpMessage` |
|
||||
| `plugin-sdk/secret-input` | Secret 输入解析 | Secret 输入辅助工具 |
|
||||
| `plugin-sdk/retry-runtime` | 重试辅助工具 | `RetryConfig`, `retryAsync`、策略运行器 |
|
||||
| `plugin-sdk/allow-from` | allowlist 格式化 | `formatAllowFromLowercase` |
|
||||
| `plugin-sdk/allowlist-resolution` | allowlist 输入映射 | `mapAllowlistResolutionInputs` |
|
||||
| `plugin-sdk/command-auth` | 命令门控和命令表面辅助工具 | `resolveControlCommandGate`、发送者授权辅助工具、命令注册表辅助工具，包括动态参数菜单格式化 |
|
||||
| `plugin-sdk/command-status` | 命令状态 / 帮助渲染器 | `buildCommandsMessage`, `buildCommandsMessagePaginated`, `buildHelpMessage` |
|
||||
| `plugin-sdk/secret-input` | 密钥输入解析 | 密钥输入辅助工具 |
|
||||
| `plugin-sdk/webhook-ingress` | webhook 请求辅助工具 | webhook 目标工具 |
|
||||
| `plugin-sdk/webhook-request-guards` | webhook body 守卫辅助工具 | 请求体读取/限制辅助工具 |
|
||||
| `plugin-sdk/webhook-request-guards` | webhook 请求体保护辅助工具 | 请求体读取 / 限制辅助工具 |
|
||||
| `plugin-sdk/reply-runtime` | 共享回复运行时 | 入站分发、心跳、回复规划器、分块 |
|
||||
| `plugin-sdk/reply-dispatch-runtime` | 窄范围回复分发辅助工具 | 最终化、provider 分发和会话标签辅助工具 |
|
||||
| `plugin-sdk/reply-dispatch-runtime` | 狭义回复分发辅助工具 | 完成、provider 分发和对话标签辅助工具 |
|
||||
| `plugin-sdk/reply-history` | 回复历史辅助工具 | `buildHistoryContext`, `buildPendingHistoryContextFromMap`, `recordPendingHistoryEntry`, `clearHistoryEntriesIfEnabled` |
|
||||
| `plugin-sdk/reply-reference` | 回复引用规划 | `createReplyReferencePlanner` |
|
||||
| `plugin-sdk/reply-chunking` | 回复分块辅助工具 | 文本/Markdown 分块辅助工具 |
|
||||
| `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 辅助工具 | 渠道/账户 Status 摘要 builders、运行时状态默认值、问题元数据辅助工具 |
|
||||
| `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` | 请求 URL 辅助工具 | 从类请求输入中提取字符串 URL |
|
||||
| `plugin-sdk/run-command` | 定时命令辅助工具 | 带规范化 stdout/stderr 的定时命令运行器 |
|
||||
| `plugin-sdk/param-readers` | 参数读取器 | 通用工具/CLI 参数读取器 |
|
||||
| `plugin-sdk/tool-payload` | 工具负载提取 | 从工具结果对象中提取规范化负载 |
|
||||
| `plugin-sdk/string-normalization-runtime` | 字符串规范化辅助工具 | slug / 字符串规范化辅助工具 |
|
||||
| `plugin-sdk/request-url` | 请求 URL 辅助工具 | 从类似请求的输入中提取字符串 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 表格辅助工具 | Markdown 表格模式辅助工具 |
|
||||
| `plugin-sdk/reply-payload` | 消息回复类型 | 回复负载类型 |
|
||||
| `plugin-sdk/provider-setup` | 精选的本地/自托管 provider 设置辅助工具 | 自托管 provider 发现/配置辅助工具 |
|
||||
| `plugin-sdk/self-hosted-provider-setup` | 聚焦的 OpenAI 兼容自托管 provider 设置辅助工具 | 同样的自托管 provider 发现/配置辅助工具 |
|
||||
| `plugin-sdk/reply-payload` | 消息回复类型 | 回复载荷类型 |
|
||||
| `plugin-sdk/provider-setup` | 精选的本地 / 自托管 provider 设置辅助工具 | 自托管 provider 发现 / 配置辅助工具 |
|
||||
| `plugin-sdk/self-hosted-provider-setup` | 聚焦的 OpenAI 兼容自托管 provider 设置辅助工具 | 同样的自托管 provider 发现 / 配置辅助工具 |
|
||||
| `plugin-sdk/provider-auth-runtime` | provider 运行时认证辅助工具 | 运行时 API key 解析辅助工具 |
|
||||
| `plugin-sdk/provider-auth-api-key` | provider API key 设置辅助工具 | API key 新手引导/profile 写入辅助工具 |
|
||||
| `plugin-sdk/provider-auth-result` | provider 认证结果辅助工具 | 标准 OAuth 认证结果 builder |
|
||||
| `plugin-sdk/provider-auth-api-key` | provider API key 设置辅助工具 | API key 新手引导 / 配置文件写入辅助工具 |
|
||||
| `plugin-sdk/provider-auth-result` | provider auth-result 辅助工具 | 标准 OAuth auth-result 构建器 |
|
||||
| `plugin-sdk/provider-auth-login` | provider 交互式登录辅助工具 | 共享交互式登录辅助工具 |
|
||||
| `plugin-sdk/provider-selection-runtime` | provider 选择辅助工具 | 已配置或自动 provider 选择，以及原始 provider 配置合并 |
|
||||
| `plugin-sdk/provider-selection-runtime` | provider 选择辅助工具 | 已配置或自动的 provider 选择，以及原始 provider 配置合并 |
|
||||
| `plugin-sdk/provider-env-vars` | provider 环境变量辅助工具 | provider 认证环境变量查找辅助工具 |
|
||||
| `plugin-sdk/provider-model-shared` | 共享 provider 模型/重放辅助工具 | `ProviderReplayFamily`、`buildProviderReplayFamilyHooks`、`normalizeModelCompat`、共享 replay-policy builders、provider 端点辅助工具以及 model-id 规范化辅助工具 |
|
||||
| `plugin-sdk/provider-model-shared` | 共享 provider 模型 / 重放辅助工具 | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`、共享重放策略构建器、provider 端点辅助工具，以及 model-id 规范化辅助工具 |
|
||||
| `plugin-sdk/provider-catalog-shared` | 共享 provider 目录辅助工具 | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` |
|
||||
| `plugin-sdk/provider-onboard` | provider onboarding 补丁 | onboarding 配置辅助工具 |
|
||||
| `plugin-sdk/provider-http` | provider HTTP 辅助工具 | 通用 provider HTTP/端点 capability 辅助工具，包括音频转录 multipart form 辅助工具 |
|
||||
| `plugin-sdk/provider-web-fetch` | provider web-fetch 辅助工具 | web-fetch provider 注册/缓存辅助工具 |
|
||||
| `plugin-sdk/provider-web-search-config-contract` | provider web-search 配置辅助工具 | 面向不需要插件启用 wiring 的 provider 的窄范围 web-search 配置/凭证辅助工具 |
|
||||
| `plugin-sdk/provider-web-search-contract` | provider web-search 契约辅助工具 | 窄范围 web-search 配置/凭证契约辅助工具，例如 `createWebSearchProviderContractFields`、`enablePluginInConfig`、`resolveProviderWebSearchPluginConfig` 以及作用域化凭证 setter/getter |
|
||||
| `plugin-sdk/provider-web-search` | provider web-search 辅助工具 | web-search provider 注册/缓存/运行时辅助工具 |
|
||||
| `plugin-sdk/provider-tools` | provider 工具/schema 兼容辅助工具 | `ProviderToolCompatFamily`、`buildProviderToolCompatFamilyHooks`、Gemini schema 清理 + 诊断，以及 xAI 兼容辅助工具，例如 `resolveXaiModelCompatPatch` / `applyXaiModelCompat` |
|
||||
| `plugin-sdk/provider-usage` | provider 用量辅助工具 | `fetchClaudeUsage`、`fetchGeminiUsage`、`fetchGithubCopilotUsage` 以及其他 provider 用量辅助工具 |
|
||||
| `plugin-sdk/provider-stream` | provider 流包装辅助工具 | `ProviderStreamFamily`、`buildProviderStreamFamilyHooks`、`composeProviderStreamWrappers`、流包装类型，以及共享的 Anthropic/Bedrock/DeepSeek V4/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot 包装辅助工具 |
|
||||
| `plugin-sdk/provider-onboard` | provider 新手引导补丁 | 新手引导配置辅助工具 |
|
||||
| `plugin-sdk/provider-http` | provider HTTP 辅助工具 | 通用 provider HTTP / 端点能力辅助工具，包括音频转录 multipart form 辅助工具 |
|
||||
| `plugin-sdk/provider-web-fetch` | provider web-fetch 辅助工具 | web-fetch provider 注册 / 缓存辅助工具 |
|
||||
| `plugin-sdk/provider-web-search-config-contract` | provider web 搜索配置辅助工具 | 适用于不需要插件启用接线的 provider 的狭义 web 搜索配置 / 凭证辅助工具 |
|
||||
| `plugin-sdk/provider-web-search-contract` | provider web 搜索契约辅助工具 | 狭义 web 搜索配置 / 凭证契约辅助工具，例如 `createWebSearchProviderContractFields`、`enablePluginInConfig`、`resolveProviderWebSearchPluginConfig`，以及作用域化凭证 setter / getter |
|
||||
| `plugin-sdk/provider-web-search` | provider web 搜索辅助工具 | web 搜索 provider 注册 / 缓存 / 运行时辅助工具 |
|
||||
| `plugin-sdk/provider-tools` | provider 工具 / 模式兼容辅助工具 | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`、Gemini 模式清理 + 诊断，以及 xAI 兼容辅助工具，例如 `resolveXaiModelCompatPatch` / `applyXaiModelCompat` |
|
||||
| `plugin-sdk/provider-usage` | provider 用量辅助工具 | `fetchClaudeUsage`, `fetchGeminiUsage`, `fetchGithubCopilotUsage`，以及其他 provider 用量辅助工具 |
|
||||
| `plugin-sdk/provider-stream` | provider 流包装辅助工具 | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`、流包装器类型，以及共享的 Anthropic / Bedrock / DeepSeek V4 / Google / Kilocode / Moonshot / OpenAI / OpenRouter / Z.A.I / MiniMax / Copilot 包装器辅助工具 |
|
||||
| `plugin-sdk/provider-transport-runtime` | provider 传输辅助工具 | 原生 provider 传输辅助工具，例如受保护 fetch、传输消息转换和可写传输事件流 |
|
||||
| `plugin-sdk/keyed-async-queue` | 有序异步队列 | `KeyedAsyncQueue` |
|
||||
| `plugin-sdk/media-runtime` | 共享媒体辅助工具 | 媒体获取/转换/存储辅助工具以及媒体负载 builders |
|
||||
| `plugin-sdk/media-generation-runtime` | 共享媒体生成辅助工具 | 图像/视频/音乐生成的共享 failover 辅助工具、候选选择和缺失模型消息 |
|
||||
| `plugin-sdk/media-understanding` | 媒体理解辅助工具 | 媒体理解 provider 类型，以及面向 provider 的图像/音频辅助工具导出 |
|
||||
| `plugin-sdk/text-runtime` | 共享文本辅助工具 | assistant 可见文本剥离、Markdown 渲染/分块/表格辅助工具、脱敏辅助工具、directive-tag 辅助工具、安全文本工具以及相关文本/日志辅助工具 |
|
||||
| `plugin-sdk/media-runtime` | 共享媒体辅助工具 | 媒体获取 / 转换 / 存储辅助工具，以及媒体载荷构建器 |
|
||||
| `plugin-sdk/media-generation-runtime` | 共享媒体生成辅助工具 | 用于图像 / 视频 / 音乐生成的共享故障切换辅助工具、候选项选择和缺失模型消息 |
|
||||
| `plugin-sdk/media-understanding` | 媒体理解辅助工具 | 媒体理解 provider 类型，以及面向 provider 的图像 / 音频辅助工具导出 |
|
||||
| `plugin-sdk/text-runtime` | 共享文本辅助工具 | 对智能体可见文本剥离、markdown 渲染 / 分块 / 表格辅助工具、脱敏辅助工具、directive-tag 辅助工具、安全文本工具，以及相关文本 / 日志辅助工具 |
|
||||
| `plugin-sdk/text-chunking` | 文本分块辅助工具 | 出站文本分块辅助工具 |
|
||||
| `plugin-sdk/speech` | 语音辅助工具 | 语音 provider 类型，以及面向 provider 的 directive、注册表和校验辅助工具 |
|
||||
| `plugin-sdk/speech-core` | 共享语音核心 | 语音 provider 类型、注册表、directive、规范化 |
|
||||
| `plugin-sdk/realtime-transcription` | 实时转录辅助工具 | provider 类型、注册表辅助工具和共享 WebSocket 会话辅助工具 |
|
||||
| `plugin-sdk/realtime-voice` | 实时语音辅助工具 | provider 类型、注册表/解析辅助工具和桥接会话辅助工具 |
|
||||
| `plugin-sdk/image-generation-core` | 共享图像生成核心 | 图像生成类型、failover、认证和注册表辅助工具 |
|
||||
| `plugin-sdk/music-generation` | 音乐生成辅助工具 | 音乐生成 provider/请求/结果类型 |
|
||||
| `plugin-sdk/music-generation-core` | 共享音乐生成核心 | 音乐生成类型、failover 辅助工具、provider 查找和模型引用解析 |
|
||||
| `plugin-sdk/video-generation` | 视频生成辅助工具 | 视频生成 provider/请求/结果类型 |
|
||||
| `plugin-sdk/video-generation-core` | 共享视频生成核心 | 视频生成类型、failover 辅助工具、provider 查找和模型引用解析 |
|
||||
| `plugin-sdk/interactive-runtime` | 交互式回复辅助工具 | 交互式回复负载规范化/归约 |
|
||||
| `plugin-sdk/channel-config-primitives` | 渠道配置原语 | 窄范围渠道 config-schema 原语 |
|
||||
| `plugin-sdk/realtime-transcription` | 实时转录辅助工具 | provider 类型、注册表辅助工具，以及共享 WebSocket 会话辅助工具 |
|
||||
| `plugin-sdk/realtime-voice` | 实时语音辅助工具 | 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/interactive-runtime` | 交互式回复辅助工具 | 交互式回复载荷规范化 / 归约 |
|
||||
| `plugin-sdk/channel-config-primitives` | 渠道配置原语 | 狭义渠道 config-schema 原语 |
|
||||
| `plugin-sdk/channel-config-writes` | 渠道配置写入辅助工具 | 渠道配置写入授权辅助工具 |
|
||||
| `plugin-sdk/channel-plugin-common` | 共享渠道前导层 | 共享渠道插件前导层导出 |
|
||||
| `plugin-sdk/channel-status` | 渠道 Status 辅助工具 | 共享渠道 Status 快照/摘要辅助工具 |
|
||||
| `plugin-sdk/allowlist-config-edit` | Allowlist 配置辅助工具 | Allowlist 配置编辑/读取辅助工具 |
|
||||
| `plugin-sdk/channel-plugin-common` | 共享渠道前导 | 共享渠道插件前导导出 |
|
||||
| `plugin-sdk/channel-status` | 渠道 Status 辅助工具 | 共享渠道状态快照 / 摘要辅助工具 |
|
||||
| `plugin-sdk/allowlist-config-edit` | allowlist 配置辅助工具 | allowlist 配置编辑 / 读取辅助工具 |
|
||||
| `plugin-sdk/group-access` | 群组访问辅助工具 | 共享群组访问决策辅助工具 |
|
||||
| `plugin-sdk/direct-dm` | 直接私信辅助工具 | 共享直接私信认证/守卫辅助工具 |
|
||||
| `plugin-sdk/extension-shared` | 共享扩展辅助工具 | 被动渠道/Status 和环境代理辅助原语 |
|
||||
| `plugin-sdk/webhook-targets` | webhook 目标辅助工具 | webhook 目标注册表和路由安装辅助工具 |
|
||||
| `plugin-sdk/direct-dm` | 直接私信辅助工具 | 共享直接私信认证 / 保护辅助工具 |
|
||||
| `plugin-sdk/extension-shared` | 共享扩展辅助工具 | 被动渠道 / 状态和环境代理辅助工具原语 |
|
||||
| `plugin-sdk/webhook-targets` | webhook 目标辅助工具 | webhook 目标注册表和 route 安装辅助工具 |
|
||||
| `plugin-sdk/webhook-path` | webhook 路径辅助工具 | webhook 路径规范化辅助工具 |
|
||||
| `plugin-sdk/web-media` | 共享 web 媒体辅助工具 | 远程/本地媒体加载辅助工具 |
|
||||
| `plugin-sdk/zod` | Zod 重新导出 | 面向插件 SDK 使用方重新导出的 `zod` |
|
||||
| `plugin-sdk/memory-core` | 内置 memory-core 辅助工具 | Memory 管理器/配置/文件/CLI 辅助接口 |
|
||||
| `plugin-sdk/memory-core-engine-runtime` | Memory 引擎运行时门面 | Memory 索引/搜索运行时门面 |
|
||||
| `plugin-sdk/memory-core-host-engine-foundation` | Memory 主机基础引擎 | Memory 主机基础引擎导出 |
|
||||
| `plugin-sdk/memory-core-host-engine-embeddings` | Memory 主机嵌入引擎 | Memory 嵌入契约、注册表访问、本地 provider 和通用批处理/远程辅助工具；具体远程 provider 位于其所属插件中 |
|
||||
| `plugin-sdk/memory-core-host-engine-qmd` | Memory 主机 QMD 引擎 | Memory 主机 QMD 引擎导出 |
|
||||
| `plugin-sdk/memory-core-host-engine-storage` | Memory 主机存储引擎 | Memory 主机存储引擎导出 |
|
||||
| `plugin-sdk/memory-core-host-multimodal` | Memory 主机多模态辅助工具 | Memory 主机多模态辅助工具 |
|
||||
| `plugin-sdk/memory-core-host-query` | Memory 主机查询辅助工具 | Memory 主机查询辅助工具 |
|
||||
| `plugin-sdk/memory-core-host-secret` | Memory 主机 secret 辅助工具 | Memory 主机 secret 辅助工具 |
|
||||
| `plugin-sdk/memory-core-host-events` | Memory 主机事件日志辅助工具 | Memory 主机事件日志辅助工具 |
|
||||
| `plugin-sdk/memory-core-host-status` | Memory 主机 Status 辅助工具 | Memory 主机 Status 辅助工具 |
|
||||
| `plugin-sdk/memory-core-host-runtime-cli` | Memory 主机 CLI 运行时 | Memory 主机 CLI 运行时辅助工具 |
|
||||
| `plugin-sdk/memory-core-host-runtime-core` | Memory 主机核心运行时 | Memory 主机核心运行时辅助工具 |
|
||||
| `plugin-sdk/memory-core-host-runtime-files` | Memory 主机文件/运行时辅助工具 | Memory 主机文件/运行时辅助工具 |
|
||||
| `plugin-sdk/memory-host-core` | Memory 主机核心运行时别名 | 面向厂商中立的 Memory 主机核心运行时辅助工具别名 |
|
||||
| `plugin-sdk/memory-host-events` | Memory 主机事件日志别名 | 面向厂商中立的 Memory 主机事件日志辅助工具别名 |
|
||||
| `plugin-sdk/memory-host-files` | Memory 主机文件/运行时别名 | 面向厂商中立的 Memory 主机文件/运行时辅助工具别名 |
|
||||
| `plugin-sdk/memory-host-markdown` | 托管 Markdown 辅助工具 | 面向 memory 邻接插件的共享托管 Markdown 辅助工具 |
|
||||
| `plugin-sdk/web-media` | 共享 web 媒体辅助工具 | 远程 / 本地媒体加载辅助工具 |
|
||||
| `plugin-sdk/zod` | Zod 重新导出 | 为插件 SDK 使用者重新导出的 `zod` |
|
||||
| `plugin-sdk/memory-core` | 内置 memory-core 辅助工具 | Memory 管理器 / 配置 / 文件 / CLI 辅助工具表面 |
|
||||
| `plugin-sdk/memory-core-engine-runtime` | Memory 引擎运行时门面 | Memory 索引 / 搜索运行时门面 |
|
||||
| `plugin-sdk/memory-core-host-engine-foundation` | Memory 宿主基础引擎 | Memory 宿主基础引擎导出 |
|
||||
| `plugin-sdk/memory-core-host-engine-embeddings` | Memory 宿主嵌入引擎 | Memory 嵌入契约、注册表访问、本地 provider 和通用批处理 / 远程辅助工具；具体远程 provider 位于其所属插件中 |
|
||||
| `plugin-sdk/memory-core-host-engine-qmd` | Memory 宿主 QMD 引擎 | Memory 宿主 QMD 引擎导出 |
|
||||
| `plugin-sdk/memory-core-host-engine-storage` | Memory 宿主存储引擎 | Memory 宿主存储引擎导出 |
|
||||
| `plugin-sdk/memory-core-host-multimodal` | Memory 宿主多模态辅助工具 | Memory 宿主多模态辅助工具 |
|
||||
| `plugin-sdk/memory-core-host-query` | Memory 宿主查询辅助工具 | Memory 宿主查询辅助工具 |
|
||||
| `plugin-sdk/memory-core-host-secret` | Memory 宿主密钥辅助工具 | Memory 宿主密钥辅助工具 |
|
||||
| `plugin-sdk/memory-core-host-events` | Memory 宿主事件日志辅助工具 | Memory 宿主事件日志辅助工具 |
|
||||
| `plugin-sdk/memory-core-host-status` | Memory 宿主状态辅助工具 | Memory 宿主状态辅助工具 |
|
||||
| `plugin-sdk/memory-core-host-runtime-cli` | Memory 宿主 CLI 运行时 | Memory 宿主 CLI 运行时辅助工具 |
|
||||
| `plugin-sdk/memory-core-host-runtime-core` | Memory 宿主核心运行时 | Memory 宿主核心运行时辅助工具 |
|
||||
| `plugin-sdk/memory-core-host-runtime-files` | Memory 宿主文件 / 运行时辅助工具 | Memory 宿主文件 / 运行时辅助工具 |
|
||||
| `plugin-sdk/memory-host-core` | Memory 宿主核心运行时别名 | 面向供应商中立的 Memory 宿主核心运行时辅助工具别名 |
|
||||
| `plugin-sdk/memory-host-events` | Memory 宿主事件日志别名 | 面向供应商中立的 Memory 宿主事件日志辅助工具别名 |
|
||||
| `plugin-sdk/memory-host-files` | Memory 宿主文件 / 运行时别名 | 面向供应商中立的 Memory 宿主文件 / 运行时辅助工具别名 |
|
||||
| `plugin-sdk/memory-host-markdown` | 托管 markdown 辅助工具 | 面向 memory 相邻插件的共享托管 markdown 辅助工具 |
|
||||
| `plugin-sdk/memory-host-search` | 活跃 Memory 搜索门面 | 惰性活跃 Memory 搜索管理器运行时门面 |
|
||||
| `plugin-sdk/memory-host-status` | Memory 主机 Status 别名 | 面向厂商中立的 Memory 主机 Status 辅助工具别名 |
|
||||
| `plugin-sdk/memory-lancedb` | 内置 memory-lancedb 辅助工具 | Memory-lancedb 辅助接口 |
|
||||
| `plugin-sdk/testing` | 测试工具 | 测试辅助工具和 mocks |
|
||||
| `plugin-sdk/memory-host-status` | Memory 宿主状态别名 | 面向供应商中立的 Memory 宿主状态辅助工具别名 |
|
||||
| `plugin-sdk/memory-lancedb` | 内置 memory-lancedb 辅助工具 | Memory-lancedb 辅助工具表面 |
|
||||
| `plugin-sdk/testing` | 测试工具 | 测试辅助工具和 mock |
|
||||
</Accordion>
|
||||
|
||||
此表刻意只包含常见迁移子集，而不是完整的 SDK
|
||||
接口。完整的 200+ 个入口点列表位于
|
||||
这个表格有意只包含常见迁移子集，而不是完整的 SDK
|
||||
表面。完整的 200+ 入口点列表位于
|
||||
`scripts/lib/plugin-sdk-entrypoints.json`。
|
||||
|
||||
该列表仍包含一些内置插件辅助接口，例如
|
||||
该列表仍包含一些内置插件辅助工具接缝，例如
|
||||
`plugin-sdk/feishu`、`plugin-sdk/feishu-setup`、`plugin-sdk/zalo`、
|
||||
`plugin-sdk/zalo-setup` 和 `plugin-sdk/matrix*`。这些接口仍然会为内置插件维护和兼容性而导出，但它们被有意排除在常见迁移表之外，也不是新插件代码的推荐目标。
|
||||
`plugin-sdk/zalo-setup` 和 `plugin-sdk/matrix*`。这些导出仍会保留，
|
||||
用于内置插件维护和兼容性，但它们被有意从常见迁移表中省略，也不是
|
||||
新插件代码的推荐目标。
|
||||
|
||||
同样的规则也适用于其他内置辅助工具家族，例如：
|
||||
|
||||
@ -415,34 +408,36 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释
|
||||
- Matrix：`plugin-sdk/matrix*`
|
||||
- LINE：`plugin-sdk/line*`
|
||||
- IRC：`plugin-sdk/irc*`
|
||||
- 内置辅助/插件接口，例如 `plugin-sdk/googlechat`、
|
||||
- 内置辅助工具 / 插件表面，例如 `plugin-sdk/googlechat`、
|
||||
`plugin-sdk/zalouser`、`plugin-sdk/bluebubbles*`、
|
||||
`plugin-sdk/mattermost*`、`plugin-sdk/msteams`、
|
||||
`plugin-sdk/nextcloud-talk`、`plugin-sdk/nostr`、`plugin-sdk/tlon`、
|
||||
`plugin-sdk/twitch`、
|
||||
`plugin-sdk/github-copilot-login`、`plugin-sdk/github-copilot-token`、
|
||||
`plugin-sdk/diagnostics-otel`、`plugin-sdk/diagnostics-prometheus`、
|
||||
`plugin-sdk/diffs`、`plugin-sdk/llm-task`、`plugin-sdk/thread-ownership`、
|
||||
和 `plugin-sdk/voice-call`
|
||||
`plugin-sdk/diffs`、`plugin-sdk/llm-task`、`plugin-sdk/thread-ownership`，
|
||||
以及 `plugin-sdk/voice-call`
|
||||
|
||||
`plugin-sdk/github-copilot-token` 当前公开的是窄范围 token 辅助接口：
|
||||
`DEFAULT_COPILOT_API_BASE_URL`、
|
||||
`plugin-sdk/github-copilot-token` 当前公开了狭义令牌辅助工具
|
||||
表面 `DEFAULT_COPILOT_API_BASE_URL`、
|
||||
`deriveCopilotApiBaseUrlFromToken` 和 `resolveCopilotApiToken`。
|
||||
|
||||
请使用与任务最匹配的最窄导入路径。如果找不到某个导出，请检查
|
||||
`src/plugin-sdk/` 下的源码，或在 Discord 中提问。
|
||||
请使用与任务最匹配的最狭义导入。如果你找不到某个导出，
|
||||
请检查 `src/plugin-sdk/` 中的源码，或在 Discord 中提问。
|
||||
|
||||
## 当前弃用项
|
||||
## 当前活跃的弃用项
|
||||
|
||||
以下是适用于插件 SDK、provider 契约、运行时接口和 manifest 的更窄范围弃用项。它们目前仍然可用，但会在未来的某个主版本中移除。每一项下方的条目都将旧 API 映射到其规范替代方案。
|
||||
以下是适用于插件 SDK、provider 契约、
|
||||
运行时表面和清单的更狭义弃用项。它们目前仍然可用，但会在未来的主要版本中移除。
|
||||
每一项下方的条目都会将旧 API 映射到其规范替代方案。
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="command-auth 帮助 builders → command-status">
|
||||
<Accordion title="command-auth 帮助构建器 → command-status">
|
||||
**旧版（`openclaw/plugin-sdk/command-auth`）**：`buildCommandsMessage`、
|
||||
`buildCommandsMessagePaginated`、`buildHelpMessage`。
|
||||
|
||||
**新版（`openclaw/plugin-sdk/command-status`）**：签名相同，导出相同——只是改为从更窄的子路径导入。`command-auth`
|
||||
会将它们作为兼容 stub 重新导出。
|
||||
**新版（`openclaw/plugin-sdk/command-status`）**：签名相同，导出也相同——只是改为从更狭义的子路径导入。`command-auth`
|
||||
将它们重新导出为兼容性桩。
|
||||
|
||||
```typescript
|
||||
// Before
|
||||
@ -460,29 +455,27 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释
|
||||
`openclaw/plugin-sdk/channel-inbound` 或
|
||||
`openclaw/plugin-sdk/channel-mention-gating`。
|
||||
|
||||
**新版**：`resolveInboundMentionDecision({ facts, policy })`——返回一个
|
||||
单一决策对象，而不是拆分成两个调用。
|
||||
**新版**：`resolveInboundMentionDecision({ facts, policy })` —— 返回的是
|
||||
单一决策对象，而不是两个拆分调用。
|
||||
|
||||
下游渠道插件（Slack、Discord、Matrix、Microsoft Teams）都已完成切换。
|
||||
下游渠道插件（Slack、Discord、Matrix、MS Teams）已经全部完成切换。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="渠道运行时 shim 和渠道 actions 辅助工具">
|
||||
`openclaw/plugin-sdk/channel-runtime` 是一个面向旧版
|
||||
渠道插件的兼容 shim。新代码不要导入它；请使用
|
||||
<Accordion title="渠道运行时 shim 和渠道动作辅助工具">
|
||||
`openclaw/plugin-sdk/channel-runtime` 是面向旧版
|
||||
渠道插件的兼容性 shim。新代码不要导入它；请改用
|
||||
`openclaw/plugin-sdk/channel-runtime-context` 来注册运行时
|
||||
对象。
|
||||
|
||||
`openclaw/plugin-sdk/channel-actions` 中的 `channelActions*` 辅助工具
|
||||
也已随着原始“actions”渠道导出一起弃用。请改为通过语义化的
|
||||
`presentation` 接口暴露 capability——渠道插件应声明它们渲染什么
|
||||
（卡片、按钮、选择器），而不是声明它们接受哪些原始 action 名称。
|
||||
会与原始 “actions” 渠道导出一起被弃用。请改为通过语义化的 `presentation` 表面公开能力——渠道插件声明它们渲染什么
|
||||
（卡片、按钮、选择器），而不是它们接受哪些原始动作名称。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Web search provider tool() 辅助工具 → 插件上的 createTool()">
|
||||
**旧版**：`openclaw/plugin-sdk/provider-web-search` 中的 `tool()`
|
||||
工厂。
|
||||
<Accordion title="Web 搜索 provider tool() 辅助工具 → 插件上的 createTool()">
|
||||
**旧版**：`openclaw/plugin-sdk/provider-web-search` 中的 `tool()` 工厂。
|
||||
|
||||
**新版**：直接在 provider 插件上实现 `createTool(...)`。
|
||||
OpenClaw 不再需要 SDK 辅助工具来注册该工具包装器。
|
||||
@ -491,57 +484,57 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释
|
||||
|
||||
<Accordion title="纯文本渠道 envelope → BodyForAgent">
|
||||
**旧版**：`formatInboundEnvelope(...)`（以及
|
||||
`ChannelMessageForAgent.channelEnvelope`），用于从入站渠道消息构建扁平的纯文本提示词
|
||||
`ChannelMessageForAgent.channelEnvelope`），用于从入站渠道消息构建扁平的纯文本提示
|
||||
envelope。
|
||||
|
||||
**新版**：`BodyForAgent` 加上结构化 user-context 块。
|
||||
渠道插件会将路由元数据（线程、话题、reply-to、reactions）作为
|
||||
类型化字段附加，而不是将它们拼接进一个提示词字符串中。
|
||||
`formatAgentEnvelope(...)` 辅助工具仍然支持用于合成的
|
||||
面向 assistant 的 envelope，但入站纯文本 envelope 正在退出使用。
|
||||
**新版**：`BodyForAgent` 加结构化用户上下文块。
|
||||
渠道插件将路由元数据（线程、主题、reply-to、reactions）作为
|
||||
带类型字段附加，而不是把它们拼接进提示字符串中。
|
||||
`formatAgentEnvelope(...)` 辅助工具对合成的、面向助手的 envelope
|
||||
仍然受支持，但入站纯文本 envelope 正在被淘汰。
|
||||
|
||||
受影响区域：`inbound_claim`、`message_received`，以及任何会对
|
||||
`channelEnvelope` 文本进行后处理的自定义渠道插件。
|
||||
受影响区域：`inbound_claim`、`message_received`，以及任何对 `channelEnvelope` 文本进行后处理的自定义
|
||||
渠道插件。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Provider discovery 类型 → provider 目录类型">
|
||||
四个 discovery 类型别名现在都只是目录时代类型的薄包装：
|
||||
<Accordion title="Provider 发现类型 → provider 目录类型">
|
||||
四个发现类型别名现在是目录时代类型的轻量包装：
|
||||
|
||||
| 旧别名 | 新类型 |
|
||||
| ------------------------- | ------------------------- |
|
||||
| `ProviderDiscoveryOrder` | `ProviderCatalogOrder` |
|
||||
| `ProviderDiscoveryContext`| `ProviderCatalogContext` |
|
||||
| `ProviderDiscoveryResult` | `ProviderCatalogResult` |
|
||||
| `ProviderPluginDiscovery` | `ProviderPluginCatalog` |
|
||||
| `ProviderDiscoveryOrder` | `ProviderCatalogOrder` |
|
||||
| `ProviderDiscoveryContext`| `ProviderCatalogContext` |
|
||||
| `ProviderDiscoveryResult` | `ProviderCatalogResult` |
|
||||
| `ProviderPluginDiscovery` | `ProviderPluginCatalog` |
|
||||
|
||||
另外还有旧版的 `ProviderCapabilities` 静态包——provider 插件
|
||||
应通过 provider 运行时契约附加 capability facts，
|
||||
以及旧版 `ProviderCapabilities` 静态集合——provider 插件
|
||||
应通过 provider 运行时契约附加能力事实，
|
||||
而不是通过静态对象。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Thinking 策略 hooks → resolveThinkingProfile">
|
||||
**旧版**（`ProviderThinkingPolicy` 上的三个独立 hook）：
|
||||
<Accordion title="Thinking 策略钩子 → resolveThinkingProfile">
|
||||
**旧版**（`ProviderThinkingPolicy` 上的三个独立钩子）：
|
||||
`isBinaryThinking(ctx)`、`supportsXHighThinking(ctx)` 和
|
||||
`resolveDefaultThinkingLevel(ctx)`。
|
||||
|
||||
**新版**：单个 `resolveThinkingProfile(ctx)`，返回一个
|
||||
`ProviderThinkingProfile`，其中包含规范的 `id`、可选的 `label` 以及
|
||||
排序后的级别列表。OpenClaw 会按配置档位自动降级过期的已存储值。
|
||||
**新版**：单一的 `resolveThinkingProfile(ctx)`，它返回一个
|
||||
`ProviderThinkingProfile`，其中包含规范 `id`、可选 `label` 和
|
||||
按级别排序的列表。OpenClaw 会按配置文件等级自动降级过期的已存储值。
|
||||
|
||||
现在实现一个 hook，而不是三个。旧版 hooks 在弃用窗口期间仍然可用，
|
||||
但不会与 profile 结果进行组合。
|
||||
现在只需实现一个钩子，而不是三个。旧版钩子在弃用窗口期间
|
||||
仍然可用，但不会与 profile 结果组合。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="外部 OAuth provider fallback → contracts.externalAuthProviders">
|
||||
**旧版**：实现 `resolveExternalOAuthProfiles(...)`，但不在
|
||||
插件 manifest 中声明该 provider。
|
||||
<Accordion title="外部 OAuth provider 回退 → contracts.externalAuthProviders">
|
||||
**旧版**：实现 `resolveExternalOAuthProfiles(...)`，
|
||||
但不在插件清单中声明该 provider。
|
||||
|
||||
**新版**：在插件 manifest 中声明 `contracts.externalAuthProviders`
|
||||
**并且**实现 `resolveExternalAuthProfiles(...)`。旧的“auth
|
||||
fallback”路径会在运行时发出警告，并将在未来移除。
|
||||
**新版**：在插件清单中声明 `contracts.externalAuthProviders`
|
||||
**并且**实现 `resolveExternalAuthProfiles(...)`。旧版 “auth
|
||||
fallback” 路径会在运行时发出警告，并将在未来移除。
|
||||
|
||||
```json
|
||||
{
|
||||
@ -554,13 +547,14 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Provider 环境变量查找 → setup.providers[].envVars">
|
||||
**旧版** manifest 字段：`providerAuthEnvVars: { anthropic: ["ANTHROPIC_API_KEY"] }`。
|
||||
**旧版** 清单字段：`providerAuthEnvVars: { anthropic: ["ANTHROPIC_API_KEY"] }`。
|
||||
|
||||
**新版**：将相同的环境变量查找信息镜像到 manifest
|
||||
中的 `setup.providers[].envVars`。这样可以将设置/Status 环境变量元数据集中在一个位置，
|
||||
并避免仅仅为了响应环境变量查找而启动插件运行时。
|
||||
**新版**：将相同的环境变量查找镜像到清单中的 `setup.providers[].envVars`
|
||||
中。这样可以将设置 / 状态环境变量元数据集中到一个
|
||||
位置，并避免仅仅为了响应环境变量查找而启动插件运行时。
|
||||
|
||||
`providerAuthEnvVars` 在弃用窗口关闭前仍通过兼容适配器继续受支持。
|
||||
`providerAuthEnvVars` 在弃用窗口关闭之前
|
||||
仍通过兼容适配器受支持。
|
||||
|
||||
</Accordion>
|
||||
|
||||
@ -570,33 +564,34 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释
|
||||
`api.registerMemoryFlushPlan(...)`、
|
||||
`api.registerMemoryRuntime(...)`。
|
||||
|
||||
**新版**：在 memory-state API 上只调用一次——
|
||||
**新版**：在 memory-state API 上使用单次调用——
|
||||
`registerMemoryCapability(pluginId, { promptBuilder, flushPlanResolver, runtime })`。
|
||||
|
||||
插槽相同，但只需一次注册调用。增量式 Memory 辅助工具
|
||||
相同槽位，单次注册调用。附加型 Memory 辅助工具
|
||||
（`registerMemoryPromptSupplement`、`registerMemoryCorpusSupplement`、
|
||||
`registerMemoryEmbeddingProvider`）不受影响。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="子智能体会话消息类型已重命名">
|
||||
<Accordion title="Subagent session messages 类型已重命名">
|
||||
两个旧版类型别名仍从 `src/plugins/runtime/types.ts` 导出：
|
||||
|
||||
| 旧版 | 新版 |
|
||||
| ----------------------------- | ------------------------------- |
|
||||
| `SubagentReadSessionParams` | `SubagentGetSessionMessagesParams` |
|
||||
| `SubagentReadSessionResult` | `SubagentGetSessionMessagesResult` |
|
||||
| `SubagentReadSessionParams` | `SubagentGetSessionMessagesParams` |
|
||||
| `SubagentReadSessionResult` | `SubagentGetSessionMessagesResult` |
|
||||
|
||||
运行时方法 `readSession` 已弃用，建议改用
|
||||
`getSessionMessages`。签名相同；旧方法会调用到新方法上。
|
||||
运行时方法 `readSession` 已弃用，替代项为
|
||||
`getSessionMessages`。签名相同；旧方法会转调
|
||||
新方法。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="runtime.tasks.flow → runtime.tasks.flows">
|
||||
**旧版**：`runtime.tasks.flow`（单数）返回一个实时的 task-flow 访问器。
|
||||
**旧版**：`runtime.tasks.flow`（单数）返回实时 task-flow 访问器。
|
||||
|
||||
**新版**：`runtime.tasks.flows`（复数）返回基于 DTO 的 Task Flow 访问接口，
|
||||
它可安全导入，并且不需要加载完整的任务运行时。
|
||||
**新版**：`runtime.tasks.flows`（复数）返回基于 DTO 的 TaskFlow 访问，
|
||||
这种方式导入安全，并且不需要加载完整任务运行时。
|
||||
|
||||
```typescript
|
||||
// Before
|
||||
@ -608,17 +603,17 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="嵌入式扩展工厂 → 智能体工具结果中间件">
|
||||
详见上文“如何迁移 → 将 Pi 工具结果扩展迁移到
|
||||
中间件”。此处列出仅为完整性：已移除的、仅适用于 Pi 的
|
||||
`api.registerEmbeddedExtensionFactory(...)` 路径，已被
|
||||
`api.registerAgentToolResultMiddleware(...)` 替代，并需要在
|
||||
`contracts.agentToolResultMiddleware` 中显式列出运行时
|
||||
上文“如何迁移 → 将 Pi 工具结果扩展迁移到中间件”中已涵盖。
|
||||
这里为完整起见再次列出：已移除的仅限 Pi 的
|
||||
`api.registerEmbeddedExtensionFactory(...)` 路径，已由
|
||||
`api.registerAgentToolResultMiddleware(...)` 替代，并在
|
||||
`contracts.agentToolResultMiddleware` 中使用显式运行时
|
||||
列表。
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="OpenClawSchemaType 别名 → OpenClawConfig">
|
||||
从 `openclaw/plugin-sdk` 重新导出的 `OpenClawSchemaType` 现在只是
|
||||
`OpenClawConfig` 的一行别名。请优先使用规范名称。
|
||||
从 `openclaw/plugin-sdk` 重新导出的 `OpenClawSchemaType`
|
||||
现在只是 `OpenClawConfig` 的一行别名。请优先使用规范名称。
|
||||
|
||||
```typescript
|
||||
// Before
|
||||
@ -631,38 +626,38 @@ OpenClaw 不会在引入替代方案的同一次变更中移除或重新解释
|
||||
</AccordionGroup>
|
||||
|
||||
<Note>
|
||||
扩展级弃用项（位于 `extensions/` 下内置渠道/provider 插件内部）
|
||||
会在它们自己的 `api.ts` 和 `runtime-api.ts`
|
||||
barrel 中跟踪。它们不影响第三方插件契约，因此未在此列出。
|
||||
如果你直接使用某个内置插件的本地 barrel，请在升级前先阅读该
|
||||
barrel 中的弃用注释。
|
||||
扩展级弃用项（位于 `extensions/` 下内置渠道 / provider 插件内部）
|
||||
在它们各自的 `api.ts` 和 `runtime-api.ts`
|
||||
barrel 中跟踪。它们不会影响第三方插件契约，因此此处未列出。
|
||||
如果你直接使用某个内置插件的本地 barrel，请在升级前
|
||||
先阅读该 barrel 中的弃用注释。
|
||||
</Note>
|
||||
|
||||
## 移除时间线
|
||||
|
||||
| 时间 | 会发生什么 |
|
||||
| ---------------------- | ----------------------------------------------------------------------- |
|
||||
| **现在** | 已弃用接口会发出运行时警告 |
|
||||
| **下一个主版本** | 已弃用接口将被移除；仍在使用它们的插件将会失效 |
|
||||
| **现在** | 已弃用表面会发出运行时警告 |
|
||||
| **下一个主要版本** | 已弃用表面将被移除；仍在使用它们的插件将会失效 |
|
||||
|
||||
所有核心插件都已完成迁移。外部插件应在下一个主版本之前完成迁移。
|
||||
所有核心插件都已经完成迁移。外部插件应在下一个主要版本之前完成迁移。
|
||||
|
||||
## 暂时抑制警告
|
||||
## 临时抑制警告
|
||||
|
||||
在迁移期间，可设置以下环境变量：
|
||||
在你着手迁移时，可以设置以下环境变量：
|
||||
|
||||
```bash
|
||||
OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 openclaw gateway run
|
||||
OPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run
|
||||
```
|
||||
|
||||
这只是临时的应急出口，不是永久解决方案。
|
||||
这是一个临时逃生舱，而不是永久解决方案。
|
||||
|
||||
## 相关内容
|
||||
|
||||
- [Getting Started](/zh-CN/plugins/building-plugins) —— 构建你的第一个插件
|
||||
- [SDK Overview](/zh-CN/plugins/sdk-overview) —— 完整子路径导入参考
|
||||
- [Channel Plugins](/zh-CN/plugins/sdk-channel-plugins) —— 构建渠道插件
|
||||
- [Provider Plugins](/zh-CN/plugins/sdk-provider-plugins) —— 构建 provider 插件
|
||||
- [Plugin Internals](/zh-CN/plugins/architecture) —— 架构深入解析
|
||||
- [Plugin Manifest](/zh-CN/plugins/manifest) —— manifest schema 参考
|
||||
- [入门指南](/zh-CN/plugins/building-plugins) — 构建你的第一个插件
|
||||
- [SDK 概览](/zh-CN/plugins/sdk-overview) — 完整子路径导入参考
|
||||
- [渠道插件](/zh-CN/plugins/sdk-channel-plugins) — 构建渠道插件
|
||||
- [提供商插件](/zh-CN/plugins/sdk-provider-plugins) — 构建 provider 插件
|
||||
- [插件内部机制](/zh-CN/plugins/architecture) — 架构深度解析
|
||||
- [插件清单](/zh-CN/plugins/manifest) — 清单模式参考
|
||||
|
||||
@ -1,28 +1,28 @@
|
||||
---
|
||||
read_when:
|
||||
- 你需要从插件中调用核心辅助函数（TTS、STT、图像生成、网页搜索、子智能体、节点）
|
||||
- 你想了解 `api.runtime` 暴露了什么
|
||||
- 你想了解 `api.runtime` 暴露了什么内容
|
||||
- 你正在从插件代码中访问配置、智能体或媒体辅助函数
|
||||
sidebarTitle: Runtime helpers
|
||||
summary: api.runtime —— 可供插件使用的注入式运行时辅助函数
|
||||
summary: api.runtime —— 提供给插件使用的注入式运行时辅助函数
|
||||
title: 插件运行时辅助函数
|
||||
x-i18n:
|
||||
generated_at: "2026-04-27T13:19:45Z"
|
||||
generated_at: "2026-04-27T13:31:46Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: dfd306203375c1a11e67f7e0e28b3cd7f15924457fa80d801cf99ae6dc8c26fa
|
||||
source_hash: a552ae4977cba7501d28c76d2ba10b79382a1e2d7a5717a75b4b9937c87eb22e
|
||||
source_path: plugins/sdk-runtime.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
每个插件在注册期间都会注入 `api.runtime` 对象，本页提供其参考说明。请使用这些辅助函数，而不是直接导入宿主内部实现。
|
||||
在注册期间注入到每个插件中的 `api.runtime` 对象参考。使用这些辅助函数，而不是直接导入宿主的内部实现。
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="渠道插件" href="/zh-CN/plugins/sdk-channel-plugins">
|
||||
分步指南，在渠道插件的上下文中使用这些辅助函数。
|
||||
在渠道插件场景中结合上下文使用这些辅助函数的分步指南。
|
||||
</Card>
|
||||
<Card title="提供商插件" href="/zh-CN/plugins/sdk-provider-plugins">
|
||||
分步指南，在提供商插件的上下文中使用这些辅助函数。
|
||||
在提供商插件场景中结合上下文使用这些辅助函数的分步指南。
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
@ -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: "restart", 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(...)` 是 `runtime-config-load-write` 下已弃用的兼容性辅助函数。它们会在运行时发出一次警告，内置插件不得使用它们；如果生产插件代码调用它们，或从插件 SDK 子路径导入这些辅助函数，配置边界保护将会失败。
|
||||
|
||||
OpenClaw 内部运行时代码也遵循相同方向：在 CLI、Gateway 网关或进程边界处加载一次配置，然后将该值一路传递下去。成功的变更写入会刷新进程运行时快照，并推进其内部修订版本；长生命周期缓存应基于运行时拥有的缓存键，而不是在本地序列化配置。长生命周期运行时模块对环境式 `loadConfig()` 调用采用零容忍扫描；请使用传入的 `cfg`、请求中的 `context.getRuntimeConfig()`，或在明确的进程边界处使用 `getRuntimeConfig()`。
|
||||
OpenClaw 内部运行时代码也遵循同样的方向：在 CLI、Gateway 网关或进程边界处加载一次配置，然后将该值向下传递。成功的变更写入会刷新进程运行时快照并推进其内部修订版本；长期缓存应基于运行时拥有的缓存键，而不是在本地序列化配置。长期运行时模块对环境式 `loadConfig()` 调用实行零容忍扫描；请使用传入的 `cfg`、请求 `context.getRuntimeConfig()`，或在显式进程边界处使用 `getRuntimeConfig()`。
|
||||
|
||||
## 运行时命名空间
|
||||
|
||||
@ -68,14 +68,14 @@ OpenClaw 内部运行时代码也遵循相同方向：在 CLI、Gateway 网关
|
||||
// 获取智能体身份
|
||||
const identity = api.runtime.agent.resolveAgentIdentity(cfg);
|
||||
|
||||
// 获取默认思考等级
|
||||
// 获取默认思考级别
|
||||
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)) {
|
||||
@ -95,18 +95,18 @@ OpenClaw 内部运行时代码也遵循相同方向：在 CLI、Gateway 网关
|
||||
runId: crypto.randomUUID(),
|
||||
sessionFile: path.join(agentDir, "sessions", "my-plugin-task-1.jsonl"),
|
||||
workspaceDir: api.runtime.agent.resolveAgentWorkspaceDir(cfg),
|
||||
prompt: "Summarize the latest changes",
|
||||
prompt: "总结最新的更改",
|
||||
timeoutMs: api.runtime.agent.resolveAgentTimeoutMs(cfg),
|
||||
});
|
||||
```
|
||||
|
||||
`runEmbeddedAgent(...)` 是一个中立的辅助函数，用于从插件代码中启动一次普通的 OpenClaw 智能体轮次。它使用与渠道触发回复相同的 provider / model 解析逻辑和智能体 harness 选择逻辑。
|
||||
`runEmbeddedAgent(...)` 是从插件代码启动普通 OpenClaw 智能体轮次的中立辅助函数。它使用与渠道触发回复相同的 provider/模型解析和智能体 harness 选择逻辑。
|
||||
|
||||
`runEmbeddedPiAgent(...)` 仍保留为兼容性别名。
|
||||
`runEmbeddedPiAgent(...)` 仍然保留为兼容性别名。
|
||||
|
||||
`resolveThinkingPolicy(...)` 返回 provider / model 支持的思考等级以及可选的默认值。提供商插件通过其思考钩子拥有模型特定配置文件，因此工具插件应调用这个运行时辅助函数，而不是导入或复制提供商列表。
|
||||
`resolveThinkingPolicy(...)` 返回 provider/模型支持的思考级别，以及可选的默认值。提供商插件通过自己的思考钩子拥有模型特定配置文件，因此工具插件应调用这个运行时辅助函数，而不是导入或复制提供商列表。
|
||||
|
||||
`normalizeThinkingLevel(...)` 会将用户文本（例如 `on`、`x-high` 或 `extra high`）转换为规范化的已存储等级，然后再根据已解析的策略进行检查。
|
||||
`normalizeThinkingLevel(...)` 会将诸如 `on`、`x-high` 或 `extra high` 之类的用户文本转换为规范化存储级别，然后再根据已解析的策略进行检查。
|
||||
|
||||
**会话存储辅助函数** 位于 `api.runtime.agent.session` 下：
|
||||
|
||||
@ -131,10 +131,10 @@ OpenClaw 内部运行时代码也遵循相同方向：在 CLI、Gateway 网关
|
||||
启动并管理后台子智能体运行。
|
||||
|
||||
```typescript
|
||||
// 启动一个子智能体运行
|
||||
// 启动一次子智能体运行
|
||||
const { runId } = await api.runtime.subagent.run({
|
||||
sessionKey: "agent:main:subagent:search-helper",
|
||||
message: "Expand this query into focused follow-up searches.",
|
||||
message: "将此查询扩展为聚焦的后续搜索。",
|
||||
provider: "openai", // 可选覆盖
|
||||
model: "gpt-4.1-mini", // 可选覆盖
|
||||
deliver: false,
|
||||
@ -149,21 +149,21 @@ OpenClaw 内部运行时代码也遵循相同方向：在 CLI、Gateway 网关
|
||||
limit: 10,
|
||||
});
|
||||
|
||||
// 删除一个会话
|
||||
// 删除会话
|
||||
await api.runtime.subagent.deleteSession({
|
||||
sessionKey: "agent:main:subagent:search-helper",
|
||||
});
|
||||
```
|
||||
|
||||
<Warning>
|
||||
模型覆盖（`provider` / `model`）需要操作员在配置中通过 `plugins.entries.<id>.subagent.allowModelOverride: true` 显式启用。不受信任的插件仍可运行子智能体，但覆盖请求会被拒绝。
|
||||
模型覆盖（`provider`/`model`）需要操作员在配置中通过 `plugins.entries.<id>.subagent.allowModelOverride: true` 显式启用。不受信任的插件仍然可以运行子智能体，但其覆盖请求会被拒绝。
|
||||
</Warning>
|
||||
|
||||
`deleteSession(...)` 可以删除同一个插件通过 `api.runtime.subagent.run(...)` 创建的会话。删除任意用户或操作员会话，仍然需要管理员作用域的 Gateway 网关请求。
|
||||
`deleteSession(...)` 可以删除同一插件通过 `api.runtime.subagent.run(...)` 创建的会话。删除任意用户或操作员会话仍然需要管理员作用域的 Gateway 网关请求。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="api.runtime.nodes">
|
||||
列出已连接的节点，并从 Gateway 网关加载的插件代码或插件 CLI 命令中调用节点宿主命令。当插件在已配对设备上拥有本地工作时，请使用此功能，例如另一台 Mac 上的浏览器桥接或音频桥接。
|
||||
列出已连接节点，并从 Gateway 网关加载的插件代码或插件 CLI 命令中调用节点宿主命令。当某个插件在配对设备上拥有本地工作时使用它，例如另一台 Mac 上的浏览器或音频桥接。
|
||||
|
||||
```typescript
|
||||
const { nodes } = await api.runtime.nodes.list({ connected: true });
|
||||
@ -176,25 +176,25 @@ OpenClaw 内部运行时代码也遵循相同方向：在 CLI、Gateway 网关
|
||||
});
|
||||
```
|
||||
|
||||
在 Gateway 网关内部，这个运行时在进程内工作。在插件 CLI 命令中，它会通过 RPC 调用已配置的 Gateway 网关，因此像 `openclaw googlemeet recover-tab` 这样的命令可以从终端检查已配对节点。节点命令仍会经过正常的 Gateway 网关节点配对、命令允许列表和节点本地命令处理流程。
|
||||
在 Gateway 网关内部，这个运行时是进程内的。在插件 CLI 命令中，它会通过 RPC 调用已配置的 Gateway 网关，因此像 `openclaw googlemeet recover-tab` 这样的命令可以从终端检查已配对节点。节点命令仍然会经过正常的 Gateway 网关节点配对、命令允许列表以及节点本地命令处理。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="api.runtime.taskFlow">
|
||||
将 Task Flow 运行时绑定到现有 OpenClaw 会话键或受信任的工具上下文，然后在每次调用时无需传递 owner 也能创建和管理 Task Flows。
|
||||
将 Task Flow 运行时绑定到现有 OpenClaw 会话键或受信任的工具上下文，然后创建和管理 Task Flows，而无需在每次调用时传递 owner。
|
||||
|
||||
```typescript
|
||||
const taskFlow = api.runtime.taskFlow.fromToolContext(ctx);
|
||||
|
||||
const created = taskFlow.createManaged({
|
||||
controllerId: "my-plugin/review-batch",
|
||||
goal: "Review new pull requests",
|
||||
goal: "审查新的拉取请求",
|
||||
});
|
||||
|
||||
const child = taskFlow.runTask({
|
||||
flowId: created.flowId,
|
||||
runtime: "acp",
|
||||
childSessionKey: "agent:main:subagent:reviewer",
|
||||
task: "Review PR #123",
|
||||
task: "审查 PR #123",
|
||||
status: "running",
|
||||
startedAt: Date.now(),
|
||||
});
|
||||
@ -211,7 +211,7 @@ OpenClaw 内部运行时代码也遵循相同方向：在 CLI、Gateway 网关
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="api.runtime.tts">
|
||||
文本转语音合成。
|
||||
文字转语音合成。
|
||||
|
||||
```typescript
|
||||
// 标准 TTS
|
||||
@ -251,7 +251,7 @@ OpenClaw 内部运行时代码也遵循相同方向：在 CLI、Gateway 网关
|
||||
const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({
|
||||
filePath: "/tmp/inbound-audio.ogg",
|
||||
cfg: api.config,
|
||||
mime: "audio/ogg", // 可选，用于无法推断 MIME 类型时
|
||||
mime: "audio/ogg", // 可选，用于无法推断 MIME 的情况
|
||||
});
|
||||
|
||||
// 描述视频
|
||||
@ -267,10 +267,10 @@ OpenClaw 内部运行时代码也遵循相同方向：在 CLI、Gateway 网关
|
||||
});
|
||||
```
|
||||
|
||||
当没有生成输出时（例如输入被跳过），返回 `{ text: undefined }`。
|
||||
当没有产生输出时（例如跳过的输入），返回 `{ text: undefined }`。
|
||||
|
||||
<Info>
|
||||
`api.runtime.stt.transcribeAudioFile(...)` 仍保留为 `api.runtime.mediaUnderstanding.transcribeAudioFile(...)` 的兼容性别名。
|
||||
`api.runtime.stt.transcribeAudioFile(...)` 仍然保留为 `api.runtime.mediaUnderstanding.transcribeAudioFile(...)` 的兼容性别名。
|
||||
</Info>
|
||||
|
||||
</Accordion>
|
||||
@ -279,7 +279,7 @@ OpenClaw 内部运行时代码也遵循相同方向：在 CLI、Gateway 网关
|
||||
|
||||
```typescript
|
||||
const result = await api.runtime.imageGeneration.generate({
|
||||
prompt: "A robot painting a sunset",
|
||||
prompt: "一个正在绘制日落的机器人",
|
||||
cfg: api.config,
|
||||
});
|
||||
|
||||
@ -288,7 +288,7 @@ OpenClaw 内部运行时代码也遵循相同方向：在 CLI、Gateway 网关
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="api.runtime.webSearch">
|
||||
网页搜索。
|
||||
Web 搜索。
|
||||
|
||||
```typescript
|
||||
const providers = api.runtime.webSearch.listProviders({ config: api.config });
|
||||
@ -340,7 +340,8 @@ OpenClaw 内部运行时代码也遵循相同方向：在 CLI、Gateway 网关
|
||||
```
|
||||
|
||||
`mutateConfigFile(...)` 和 `replaceConfigFile(...)` 会返回一个 `followUp`
|
||||
值，例如 `{ mode: "restart", requiresRestart: true, reason }`，用于记录写入方的意图，同时不会从 Gateway 网关手中夺走重启控制权。
|
||||
值，例如 `{ mode: "restart", requiresRestart: true, reason }`，
|
||||
用于记录写入方的意图，同时不会从 Gateway 网关手中夺走重启控制权。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="api.runtime.system">
|
||||
@ -407,7 +408,7 @@ OpenClaw 内部运行时代码也遵循相同方向：在 CLI、Gateway 网关
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="api.runtime.channel">
|
||||
渠道特定的运行时辅助函数（在加载渠道插件时可用）。
|
||||
渠道专用运行时辅助函数（在加载渠道插件时可用）。
|
||||
|
||||
`api.runtime.channel.mentions` 是供使用运行时注入的内置渠道插件共享的入站提及策略接口：
|
||||
|
||||
@ -444,7 +445,7 @@ OpenClaw 内部运行时代码也遵循相同方向：在 CLI、Gateway 网关
|
||||
- `implicitMentionKindWhen`
|
||||
- `resolveInboundMentionDecision`
|
||||
|
||||
`api.runtime.channel.mentions` 有意不暴露较旧的 `resolveMentionGating*` 兼容性辅助函数。请优先使用规范化的 `{ facts, policy }` 路径。
|
||||
`api.runtime.channel.mentions` 故意不暴露较旧的 `resolveMentionGating*` 兼容性辅助函数。请优先使用规范化的 `{ facts, policy }` 路径。
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@ -466,7 +467,7 @@ OpenClaw 内部运行时代码也遵循相同方向：在 CLI、Gateway 网关
|
||||
```
|
||||
|
||||
</Step>
|
||||
<Step title="连接到入口点">
|
||||
<Step title="接入入口点">
|
||||
```typescript
|
||||
export default defineChannelPluginEntry({
|
||||
id: "my-plugin",
|
||||
@ -492,7 +493,7 @@ OpenClaw 内部运行时代码也遵循相同方向：在 CLI、Gateway 网关
|
||||
</Steps>
|
||||
|
||||
<Note>
|
||||
运行时存储的标识应优先使用 `pluginId`。更底层的 `key` 形式适用于少见场景：某个插件有意需要多个运行时槽位。
|
||||
运行时存储标识优先使用 `pluginId`。更底层的 `key` 形式用于不常见场景，即某个插件有意需要多个运行时槽位。
|
||||
</Note>
|
||||
|
||||
## 其他顶层 `api` 字段
|
||||
@ -506,7 +507,7 @@ OpenClaw 内部运行时代码也遵循相同方向：在 CLI、Gateway 网关
|
||||
插件显示名称。
|
||||
</ParamField>
|
||||
<ParamField path="api.config" type="OpenClawConfig">
|
||||
当前配置快照（如果可用，则为当前处于活动状态的内存运行时快照）。
|
||||
当前配置快照（如可用，则为当前激活的内存中运行时快照）。
|
||||
</ParamField>
|
||||
<ParamField path="api.pluginConfig" type="Record<string, unknown>">
|
||||
来自 `plugins.entries.<id>.config` 的插件专用配置。
|
||||
@ -515,7 +516,7 @@ OpenClaw 内部运行时代码也遵循相同方向：在 CLI、Gateway 网关
|
||||
作用域日志记录器（`debug`、`info`、`warn`、`error`）。
|
||||
</ParamField>
|
||||
<ParamField path="api.registrationMode" type="PluginRegistrationMode">
|
||||
当前加载模式；`"setup-runtime"` 是完整入口启动 / 设置之前的轻量级窗口。
|
||||
当前加载模式；`"setup-runtime"` 是完整入口启动/设置之前的轻量级预备窗口。
|
||||
</ParamField>
|
||||
<ParamField path="api.resolvePath(input)" type="(string) => string">
|
||||
解析相对于插件根目录的路径。
|
||||
|
||||
@ -1,30 +1,29 @@
|
||||
---
|
||||
read_when:
|
||||
- 你想在 OpenClaw 中使用 Google Gemini 模型
|
||||
- 你需要使用 API 密钥或 OAuth 认证流程
|
||||
- 你需要 API 密钥或 OAuth 认证流程
|
||||
summary: Google Gemini 设置（API 密钥 + OAuth、图像生成、媒体理解、TTS、网页搜索）
|
||||
title: Google（Gemini）
|
||||
x-i18n:
|
||||
generated_at: "2026-04-27T06:52:23Z"
|
||||
generated_at: "2026-04-27T13:31:45Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 7130cd7e13a4ca76572572bb77f1926be0fbe1fa4e1d3c0f9619d31ba564a163
|
||||
source_hash: 4ab97fc37ba78af8273987ec95f71bc599abf4e0a42ca597775f32ba04a03033
|
||||
source_path: providers/google.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
Google 插件通过 Google AI Studio 提供对 Gemini 模型的访问，此外还支持
|
||||
通过 Gemini Grounding 进行图像生成、媒体理解（图像/音频/视频）、文本转语音以及网页搜索。
|
||||
Google 插件通过 Google AI Studio 提供对 Gemini 模型的访问，还提供通过 Gemini Grounding 实现的图像生成、媒体理解（图像/音频/视频）、文本转语音和网页搜索。
|
||||
|
||||
- 提供商：`google`
|
||||
- 认证：`GEMINI_API_KEY` 或 `GOOGLE_API_KEY`
|
||||
- API：Google Gemini API
|
||||
- 运行时选项：`agents.defaults.agentRuntime.id: "google-gemini-cli"`
|
||||
会复用 Gemini CLI OAuth，同时保持模型引用规范为 `google/*`。
|
||||
可复用 Gemini CLI OAuth，同时将模型引用规范保持为 `google/*`。
|
||||
|
||||
## 入门指南
|
||||
|
||||
选择你偏好的认证方式，并按照设置步骤进行操作。
|
||||
选择你偏好的认证方式，并按照设置步骤操作。
|
||||
|
||||
<Tabs>
|
||||
<Tab title="API 密钥">
|
||||
@ -36,7 +35,7 @@ Google 插件通过 Google AI Studio 提供对 Gemini 模型的访问，此外
|
||||
openclaw onboard --auth-choice gemini-api-key
|
||||
```
|
||||
|
||||
或直接传入密钥：
|
||||
或者直接传入密钥：
|
||||
|
||||
```bash
|
||||
openclaw onboard --non-interactive \
|
||||
@ -70,27 +69,26 @@ Google 插件通过 Google AI Studio 提供对 Gemini 模型的访问，此外
|
||||
</Tab>
|
||||
|
||||
<Tab title="Gemini CLI（OAuth）">
|
||||
**最适合：** 复用现有的 Gemini CLI 登录，通过 PKCE OAuth 认证，而不是单独使用 API 密钥。
|
||||
**最适合：** 复用现有的 Gemini CLI 登录，通过 PKCE OAuth 代替单独的 API 密钥。
|
||||
|
||||
<Warning>
|
||||
`google-gemini-cli` provider 是非官方集成。一些用户
|
||||
报告称，以这种方式使用 OAuth 时会遇到账户限制。请自行承担风险。
|
||||
`google-gemini-cli` 提供商是非官方集成。一些用户报告称，
|
||||
以这种方式使用 OAuth 时会遇到账户限制。请自行承担使用风险。
|
||||
</Warning>
|
||||
|
||||
<Steps>
|
||||
<Step title="安装 Gemini CLI">
|
||||
本地 `gemini` 命令必须可在 `PATH` 中使用。
|
||||
本地 `gemini` 命令必须可在 `PATH` 中找到。
|
||||
|
||||
```bash
|
||||
# Homebrew
|
||||
brew install gemini-cli
|
||||
|
||||
# 或 npm
|
||||
# or npm
|
||||
npm install -g @google/gemini-cli
|
||||
```
|
||||
|
||||
OpenClaw 同时支持 Homebrew 安装和全局 npm 安装，包括
|
||||
常见的 Windows/npm 布局。
|
||||
OpenClaw 同时支持 Homebrew 安装和全局 npm 安装，包括常见的 Windows/npm 布局。
|
||||
</Step>
|
||||
<Step title="通过 OAuth 登录">
|
||||
```bash
|
||||
@ -116,52 +114,49 @@ Google 插件通过 Google AI Studio 提供对 Gemini 模型的访问，此外
|
||||
（或使用 `GEMINI_CLI_*` 变体。）
|
||||
|
||||
<Note>
|
||||
如果 Gemini CLI OAuth 请求在登录后失败，请在 Gateway 网关主机上设置 `GOOGLE_CLOUD_PROJECT` 或
|
||||
`GOOGLE_CLOUD_PROJECT_ID`，然后重试。
|
||||
如果 Gemini CLI OAuth 在登录后请求失败，请在 Gateway 网关主机上设置 `GOOGLE_CLOUD_PROJECT` 或 `GOOGLE_CLOUD_PROJECT_ID`，然后重试。
|
||||
</Note>
|
||||
|
||||
<Note>
|
||||
如果在浏览器流程开始之前登录失败，请确认本地 `gemini`
|
||||
如果登录在浏览器流程开始前就失败，请确认本地 `gemini`
|
||||
命令已安装并且位于 `PATH` 中。
|
||||
</Note>
|
||||
|
||||
`google-gemini-cli/*` 模型引用属于旧版兼容别名。新的
|
||||
配置应使用 `google/*` 模型引用，并搭配 `google-gemini-cli`
|
||||
运行时，以便在需要本地 Gemini CLI 执行时使用。
|
||||
`google-gemini-cli/*` 模型引用属于旧版兼容别名。新配置应使用 `google/*` 模型引用，并在需要本地 Gemini CLI 执行时搭配 `google-gemini-cli`
|
||||
运行时。
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## 功能
|
||||
|
||||
| 功能 | 支持情况 |
|
||||
| ---------------------- | ----------------------------- |
|
||||
| 聊天补全 | 是 |
|
||||
| 图像生成 | 是 |
|
||||
| 音乐生成 | 是 |
|
||||
| 文本转语音 | 是 |
|
||||
| 实时语音 | 是（Google Live API） |
|
||||
| 图像理解 | 是 |
|
||||
| 音频转录 | 是 |
|
||||
| 视频理解 | 是 |
|
||||
| 网页搜索（Grounding） | 是 |
|
||||
| 思考/推理 | 是（Gemini 2.5+ / Gemini 3+） |
|
||||
| Gemma 4 模型 | 是 |
|
||||
| 功能 | 支持情况 |
|
||||
| ------------------------ | ----------------------------- |
|
||||
| 聊天补全 | 是 |
|
||||
| 图像生成 | 是 |
|
||||
| 音乐生成 | 是 |
|
||||
| 文本转语音 | 是 |
|
||||
| 实时语音 | 是（Google Live API） |
|
||||
| 图像理解 | 是 |
|
||||
| 音频转写 | 是 |
|
||||
| 视频理解 | 是 |
|
||||
| 网页搜索（Grounding） | 是 |
|
||||
| Thinking/推理 | 是（Gemini 2.5+ / Gemini 3+） |
|
||||
| Gemma 4 模型 | 是 |
|
||||
|
||||
<Tip>
|
||||
Gemini 3 模型使用 `thinkingLevel`，而不是 `thinkingBudget`。OpenClaw 会将
|
||||
Gemini 3 模型使用 `thinkingLevel` 而不是 `thinkingBudget`。OpenClaw 会将
|
||||
Gemini 3、Gemini 3.1 和 `gemini-*-latest` 别名的推理控制映射到
|
||||
`thinkingLevel`，这样默认/低延迟运行就不会发送被禁用的
|
||||
`thinkingBudget` 值。
|
||||
|
||||
`/think adaptive` 会保留 Google 的动态思考语义，而不是选择
|
||||
一个固定的 OpenClaw 级别。Gemini 3 和 Gemini 3.1 会省略固定的 `thinkingLevel`，以便
|
||||
Google 自行选择级别；Gemini 2.5 会发送 Google 的动态哨兵值
|
||||
`/think adaptive` 会保留 Google 的动态 thinking 语义，而不是选择一个固定的 OpenClaw 级别。Gemini 3 和 Gemini 3.1 不会发送固定的 `thinkingLevel`，因此
|
||||
Google 可以自行选择级别；Gemini 2.5 会发送 Google 的动态哨兵值
|
||||
`thinkingBudget: -1`。
|
||||
|
||||
Gemma 4 模型（例如 `gemma-4-26b-a4b-it`）支持思考模式。OpenClaw
|
||||
会将 `thinkingBudget` 重写为 Google 支持的 `thinkingLevel`，用于 Gemma 4。
|
||||
将 thinking 设置为 `off` 时，会保留禁用状态，而不是映射到
|
||||
Gemma 4 模型（例如 `gemma-4-26b-a4b-it`）支持 thinking 模式。OpenClaw
|
||||
会将 `thinkingBudget` 重写为 Google 支持的 `thinkingLevel`，以用于 Gemma 4。
|
||||
将 thinking 设置为 `off` 时，会保留 thinking 禁用状态，而不会映射为
|
||||
`MINIMAL`。
|
||||
</Tip>
|
||||
|
||||
@ -170,9 +165,9 @@ Gemma 4 模型（例如 `gemma-4-26b-a4b-it`）支持思考模式。OpenClaw
|
||||
内置的 `google` 图像生成提供商默认使用
|
||||
`google/gemini-3.1-flash-image-preview`。
|
||||
|
||||
- 同时支持 `google/gemini-3-pro-image-preview`
|
||||
- 也支持 `google/gemini-3-pro-image-preview`
|
||||
- 生成：每次请求最多 4 张图像
|
||||
- 编辑模式：已启用，最多可输入 5 张图像
|
||||
- 编辑模式：已启用，最多支持 5 张输入图像
|
||||
- 几何控制：`size`、`aspectRatio` 和 `resolution`
|
||||
|
||||
要将 Google 用作默认图像提供商：
|
||||
@ -199,7 +194,7 @@ Gemma 4 模型（例如 `gemma-4-26b-a4b-it`）支持思考模式。OpenClaw
|
||||
`video_generate` 工具注册了视频生成功能。
|
||||
|
||||
- 默认视频模型：`google/veo-3.1-fast-generate-preview`
|
||||
- 模式：文生视频、图生视频，以及单视频参考流程
|
||||
- 模式：文本生成视频、图像生成视频，以及单视频参考流程
|
||||
- 支持 `aspectRatio`、`resolution` 和 `audio`
|
||||
- 当前时长限制：**4 到 8 秒**
|
||||
|
||||
@ -227,7 +222,7 @@ Gemma 4 模型（例如 `gemma-4-26b-a4b-it`）支持思考模式。OpenClaw
|
||||
`music_generate` 工具注册了音乐生成功能。
|
||||
|
||||
- 默认音乐模型：`google/lyria-3-clip-preview`
|
||||
- 同时支持 `google/lyria-3-pro-preview`
|
||||
- 也支持 `google/lyria-3-pro-preview`
|
||||
- 提示词控制：`lyrics` 和 `instrumental`
|
||||
- 输出格式：默认 `mp3`，另外在 `google/lyria-3-pro-preview` 上支持 `wav`
|
||||
- 参考输入：最多 10 张图像
|
||||
@ -258,8 +253,8 @@ Gemma 4 模型（例如 `gemma-4-26b-a4b-it`）支持思考模式。OpenClaw
|
||||
|
||||
- 默认语音：`Kore`
|
||||
- 认证：`messages.tts.providers.google.apiKey`、`models.providers.google.apiKey`、`GEMINI_API_KEY` 或 `GOOGLE_API_KEY`
|
||||
- 输出：常规 TTS 附件输出 WAV，语音便笺目标输出 Opus，Talk/电话场景输出 PCM
|
||||
- 语音便笺输出：Google PCM 会包装为 WAV，并通过 `ffmpeg` 转码为 48 kHz Opus
|
||||
- 输出：常规 TTS 附件使用 WAV，语音便签目标使用 Opus，Talk/电话场景使用 PCM
|
||||
- 语音便签输出：Google PCM 会被封装为 WAV，并通过 `ffmpeg` 转码为 48 kHz Opus
|
||||
|
||||
要将 Google 用作默认 TTS 提供商：
|
||||
|
||||
@ -282,13 +277,13 @@ Gemma 4 模型（例如 `gemma-4-26b-a4b-it`）支持思考模式。OpenClaw
|
||||
```
|
||||
|
||||
Gemini API TTS 使用自然语言提示来控制风格。设置
|
||||
`audioProfile` 可在朗读文本前添加一个可复用的风格提示。若你的提示文本中提到了某个具名说话者，请设置
|
||||
`audioProfile` 可在朗读文本前添加可复用的风格提示。若你的提示文本提到了具名说话人，请设置
|
||||
`speakerName`。
|
||||
|
||||
Gemini API TTS 还接受文本中的方括号表达式音频标签，
|
||||
例如 `[whispers]` 或 `[laughs]`。如果你想让这些标签不出现在可见聊天回复中，
|
||||
但仍发送给 TTS，请将它们放在 `[[tts:text]]...[[/tts:text]]`
|
||||
块内：
|
||||
Gemini API TTS 还接受文本中的方括号表现力音频标签，
|
||||
例如 `[whispers]` 或 `[laughs]`。为了让这些标签不出现在可见的聊天回复中，
|
||||
但仍发送给 TTS，请将它们放入 `[[tts:text]]...[[/tts:text]]`
|
||||
块中：
|
||||
|
||||
```text
|
||||
Here is the clean reply text.
|
||||
@ -297,29 +292,29 @@ Here is the clean reply text.
|
||||
```
|
||||
|
||||
<Note>
|
||||
仅限制用于 Gemini API 的 Google Cloud Console API 密钥对该
|
||||
提供商有效。这不是单独的 Cloud Text-to-Speech API 路径。
|
||||
将 API 密钥限制为 Gemini API 的 Google Cloud Console API 密钥可用于此
|
||||
提供商。这不是单独的 Cloud Text-to-Speech API 路径。
|
||||
</Note>
|
||||
|
||||
## 实时语音
|
||||
|
||||
内置的 `google` 插件注册了一个由
|
||||
Gemini Live API 驱动的实时语音提供商，用于 Voice Call 和 Google Meet 等后端音频桥接场景。
|
||||
Gemini Live API 支持的实时语音提供商，用于 Voice Call 和 Google Meet 等后端音频桥接场景。
|
||||
|
||||
| 设置 | 配置路径 | 默认值 |
|
||||
| --------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
|
||||
| 模型 | `plugins.entries.voice-call.config.realtime.providers.google.model` | `gemini-2.5-flash-native-audio-preview-12-2025` |
|
||||
| 语音 | `...google.voice` | `Kore` |
|
||||
| Temperature | `...google.temperature` | （未设置） |
|
||||
| VAD 起始灵敏度 | `...google.startSensitivity` | （未设置） |
|
||||
| VAD 结束灵敏度 | `...google.endSensitivity` | （未设置） |
|
||||
| 静音时长 | `...google.silenceDurationMs` | （未设置） |
|
||||
| 活动处理 | `...google.activityHandling` | Google 默认值，`start-of-activity-interrupts` |
|
||||
| 轮次覆盖范围 | `...google.turnCoverage` | Google 默认值，`only-activity` |
|
||||
| 禁用自动 VAD | `...google.automaticActivityDetectionDisabled` | `false` |
|
||||
| API 密钥 | `...google.apiKey` | 回退到 `models.providers.google.apiKey`、`GEMINI_API_KEY` 或 `GOOGLE_API_KEY` |
|
||||
| 设置 | 配置路径 | 默认值 |
|
||||
| ----------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
|
||||
| 模型 | `plugins.entries.voice-call.config.realtime.providers.google.model` | `gemini-2.5-flash-native-audio-preview-12-2025` |
|
||||
| 语音 | `...google.voice` | `Kore` |
|
||||
| Temperature | `...google.temperature` | （未设置） |
|
||||
| VAD 开始灵敏度 | `...google.startSensitivity` | （未设置） |
|
||||
| VAD 结束灵敏度 | `...google.endSensitivity` | （未设置） |
|
||||
| 静音时长 | `...google.silenceDurationMs` | （未设置） |
|
||||
| 活动处理 | `...google.activityHandling` | Google 默认值，`start-of-activity-interrupts` |
|
||||
| 轮次覆盖范围 | `...google.turnCoverage` | Google 默认值，`only-activity` |
|
||||
| 禁用自动 VAD | `...google.automaticActivityDetectionDisabled` | `false` |
|
||||
| API 密钥 | `...google.apiKey` | 回退到 `models.providers.google.apiKey`、`GEMINI_API_KEY` 或 `GOOGLE_API_KEY` |
|
||||
|
||||
示例 Voice Call 实时配置：
|
||||
Voice Call 实时配置示例：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -349,33 +344,37 @@ Gemini Live API 驱动的实时语音提供商，用于 Voice Call 和 Google Me
|
||||
|
||||
<Note>
|
||||
Google Live API 通过 WebSocket 使用双向音频和函数调用。
|
||||
OpenClaw 会将电话/Meet 桥接音频适配到 Gemini 的 PCM Live API 流，并且
|
||||
让工具调用保持在共享的实时语音契约上。除非你需要调整采样行为，否则请将 `temperature`
|
||||
保持为未设置；OpenClaw 会省略非正值，
|
||||
因为当 `temperature: 0` 时，Google Live 可能返回仅有转录而没有音频的结果。
|
||||
OpenClaw 会将电话/Meet 桥接音频适配到 Gemini 的 PCM Live API 流，
|
||||
并将工具调用保持在共享的实时语音契约上。除非你需要调整采样行为，否则请将 `temperature`
|
||||
保持未设置；OpenClaw 会省略非正值，
|
||||
因为 Google Live 在 `temperature: 0` 时可能返回只有转录文本而没有音频的结果。
|
||||
Gemini API 转录在不设置 `languageCodes` 的情况下启用；当前的 Google
|
||||
SDK 会在此 API 路径上拒绝语言代码提示。
|
||||
</Note>
|
||||
|
||||
<Note>
|
||||
Control UI Talk 浏览器会话仍然需要一个具有
|
||||
浏览器 WebRTC 会话实现的实时语音提供商。目前该路径是 OpenAI Realtime；而
|
||||
Google 提供商用于后端实时桥接。
|
||||
Control UI Talk 支持使用受限的一次性令牌进行 Google Live 浏览器会话。
|
||||
仅后端的实时语音提供商也可以通过通用的
|
||||
Gateway 网关中继传输运行，从而将提供商凭证保留在 Gateway 网关上。
|
||||
</Note>
|
||||
|
||||
对于维护者实时验证，请运行
|
||||
`OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts`。
|
||||
Google 分支会铸造与 Control
|
||||
UI Talk 所使用的同一种受限 Live API 令牌结构，打开浏览器 WebSocket 端点，发送初始设置载荷，
|
||||
并等待 `setupComplete`。
|
||||
|
||||
## 高级配置
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="直接复用 Gemini 缓存">
|
||||
对于直接的 Gemini API 运行（`api: "google-generative-ai"`），OpenClaw
|
||||
会将已配置的 `cachedContent` 句柄直接传递给 Gemini 请求。
|
||||
对于直接 Gemini API 运行（`api: "google-generative-ai"`），OpenClaw
|
||||
会将已配置的 `cachedContent` 句柄透传给 Gemini 请求。
|
||||
|
||||
- 可使用 `cachedContent` 或旧版 `cached_content`
|
||||
为每个模型或全局参数进行配置
|
||||
- 如果两者同时存在，以 `cachedContent` 为准
|
||||
- 使用 `cachedContent` 或旧版 `cached_content` 配置按模型或全局参数
|
||||
- 如果两者都存在，则以 `cachedContent` 为准
|
||||
- 示例值：`cachedContents/prebuilt-context`
|
||||
- Gemini 的缓存命中用量会从上游的 `cachedContentTokenCount`
|
||||
规范化为 OpenClaw 的 `cacheRead`
|
||||
- Gemini 的缓存命中用量会从上游的 `cachedContentTokenCount` 规范化为 OpenClaw `cacheRead`
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -396,19 +395,19 @@ Google 提供商用于后端实时桥接。
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Gemini CLI JSON 使用说明">
|
||||
使用 `google-gemini-cli` OAuth provider 时，OpenClaw 会按如下方式规范化
|
||||
使用 `google-gemini-cli` OAuth 提供商时，OpenClaw 会按如下方式规范化
|
||||
CLI JSON 输出：
|
||||
|
||||
- 回复文本来自 CLI JSON 的 `response` 字段。
|
||||
- 当 CLI 将 `usage` 留空时，用量会回退到 `stats`。
|
||||
- `stats.cached` 会被规范化为 OpenClaw 的 `cacheRead`。
|
||||
- `stats.cached` 会被规范化为 OpenClaw `cacheRead`。
|
||||
- 如果缺少 `stats.input`，OpenClaw 会根据
|
||||
`stats.input_tokens - stats.cached` 推导输入 token 数。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="环境和守护进程设置">
|
||||
如果 Gateway 网关以守护进程方式运行（launchd/systemd），请确保 `GEMINI_API_KEY`
|
||||
如果 Gateway 网关以守护进程（launchd/systemd）运行，请确保 `GEMINI_API_KEY`
|
||||
对该进程可用（例如放在 `~/.openclaw/.env` 中，或通过
|
||||
`env.shellEnv` 提供）。
|
||||
</Accordion>
|
||||
|
||||
@ -3,96 +3,82 @@ read_when:
|
||||
- 你想在 OpenClaw 中使用 OpenAI 模型
|
||||
- 你想使用 Codex 订阅认证，而不是 API 密钥
|
||||
- 你需要更严格的 GPT-5 智能体执行行为
|
||||
summary: 在 OpenClaw 中通过 API 密钥或 Codex 订阅使用 OpenAI
|
||||
summary: 在 OpenClaw 中使用 OpenAI 的 API 密钥或 Codex 订阅
|
||||
title: OpenAI
|
||||
x-i18n:
|
||||
generated_at: "2026-04-27T11:00:51Z"
|
||||
generated_at: "2026-04-27T13:31:48Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: e2ef019ca3d8ed1de0e4ac8da02fec781e71e1ced551034383d7f4d306795193
|
||||
source_hash: f6a33485bb8372dca81d91d35a4fddca315613336adf601efa7ef9a418bf8480
|
||||
source_path: providers/openai.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
OpenAI 为 GPT 模型提供开发者 API，而 Codex 也可以通过 OpenAI 的 Codex 客户端，作为 ChatGPT 套餐中的编程智能体使用。OpenClaw 将这些 surface 分开处理，以保持配置可预测。
|
||||
OpenAI 为 GPT 模型提供开发者 API，而 Codex 也可通过 OpenAI 的 Codex 客户端，作为 ChatGPT 计划中的编码智能体使用。OpenClaw 将这些能力面分开处理，以便让配置保持可预测。
|
||||
|
||||
OpenClaw 支持三种 OpenAI 系列路线。模型前缀用于选择
|
||||
provider/认证路线；单独的运行时设置用于选择由谁执行嵌入式
|
||||
Agent loop：
|
||||
OpenClaw 支持三种 OpenAI 家族路由。模型前缀用于选择提供商 / 认证路由；另一个单独的运行时设置用于选择由谁执行嵌入式 Agent loop：
|
||||
|
||||
- **API 密钥** — 通过按量计费直接访问 OpenAI Platform（`openai/*` 模型）
|
||||
- **通过 PI 使用 Codex 订阅** — 使用 ChatGPT/Codex 登录并通过订阅访问（`openai-codex/*` 模型）
|
||||
- **Codex app-server harness** — 原生 Codex app-server 执行（`openai/*` 模型，外加 `agents.defaults.agentRuntime.id: "codex"`）
|
||||
- **API 密钥** — 通过直接 OpenAI Platform 访问并按用量计费（`openai/*` 模型）
|
||||
- **通过 PI 的 Codex 订阅** — 使用 ChatGPT/Codex 登录并通过订阅访问（`openai-codex/*` 模型）
|
||||
- **Codex app-server harness** — 原生 Codex app-server 执行（`openai/*` 模型，加上 `agents.defaults.agentRuntime.id: "codex"`）
|
||||
|
||||
OpenAI 明确支持在 OpenClaw 这类外部工具和工作流中使用基于订阅的 OAuth。
|
||||
OpenAI 明确支持在像 OpenClaw 这样的外部工具和工作流中使用订阅 OAuth。
|
||||
|
||||
provider、model、运行时和渠道是相互独立的层。如果你把这些标签混在一起了，请在修改配置之前先阅读 [Agent Runtimes](/zh-CN/concepts/agent-runtimes)。
|
||||
提供商、模型、运行时和渠道是彼此独立的层。如果你把这些标签混在一起了，请先阅读 [Agent Runtimes](/zh-CN/concepts/agent-runtimes)，再修改配置。
|
||||
|
||||
## 快速选择
|
||||
|
||||
| 目标 | 使用方式 | 说明 |
|
||||
| --------------------------------------------- | ------------------------------------------------ | -------------------------------------------------------------------------- |
|
||||
| 直接使用 API 密钥计费 | `openai/gpt-5.5` | 设置 `OPENAI_API_KEY` 或运行 OpenAI API 密钥新手引导。 |
|
||||
| 使用 ChatGPT/Codex 订阅认证的 GPT-5.5 | `openai-codex/gpt-5.5` | Codex OAuth 的默认 PI 路线。是订阅配置的首选方案。 |
|
||||
| 使用原生 Codex app-server 行为的 GPT-5.5 | `openai/gpt-5.5` 加 `agentRuntime.id: "codex"` | 为该模型引用强制使用 Codex app-server harness。 |
|
||||
| 图像生成或编辑 | `openai/gpt-image-2` | 可与 `OPENAI_API_KEY` 或 OpenAI Codex OAuth 一起使用。 |
|
||||
| 透明背景图像 | `openai/gpt-image-1.5` | 使用 `outputFormat=png` 或 `webp`，并设置 `openai.background=transparent`。 |
|
||||
| 目标 | 使用方式 | 说明 |
|
||||
| --------------------------------------------- | ------------------------------------------------ | ---------------------------------------------------------------------------- |
|
||||
| 直接 API 密钥计费 | `openai/gpt-5.5` | 设置 `OPENAI_API_KEY`，或运行 OpenAI API 密钥新手引导。 |
|
||||
| 使用 ChatGPT/Codex 订阅认证的 GPT-5.5 | `openai-codex/gpt-5.5` | Codex OAuth 的默认 PI 路由。对于订阅配置，这是最佳首选。 |
|
||||
| 使用原生 Codex app-server 行为的 GPT-5.5 | `openai/gpt-5.5` 加 `agentRuntime.id: "codex"` | 为该模型引用强制使用 Codex app-server harness。 |
|
||||
| 图像生成或编辑 | `openai/gpt-image-2` | 可与 `OPENAI_API_KEY` 或 OpenAI Codex OAuth 搭配使用。 |
|
||||
| 透明背景图像 | `openai/gpt-image-1.5` | 使用 `outputFormat=png` 或 `webp`，并设置 `openai.background=transparent`。 |
|
||||
|
||||
## 命名映射
|
||||
|
||||
这些名称看起来相似，但不能互换：
|
||||
|
||||
| 你看到的名称 | 层级 | 含义 |
|
||||
| ---------------------------------- | ----------------- | -------------------------------------------------------------------------------------- |
|
||||
| `openai` | provider 前缀 | 直接的 OpenAI Platform API 路线。 |
|
||||
| `openai-codex` | provider 前缀 | 通过普通 OpenClaw PI 运行器走 OpenAI Codex OAuth/订阅路线。 |
|
||||
| `codex` plugin | 插件 | OpenClaw 内置插件，提供原生 Codex app-server 运行时和 `/codex` 聊天控制。 |
|
||||
| `agentRuntime.id: codex` | Agent 运行时 | 为嵌入式轮次强制使用原生 Codex app-server harness。 |
|
||||
| `/codex ...` | 聊天命令集 | 从会话中绑定/控制 Codex app-server 线程。 |
|
||||
| `runtime: "acp", agentId: "codex"` | ACP 会话路线 | 通过 ACP/acpx 运行 Codex 的显式回退路径。 |
|
||||
| 你看到的名称 | 层级 | 含义 |
|
||||
| ---------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------- |
|
||||
| `openai` | 提供商前缀 | 直接 OpenAI Platform API 路由。 |
|
||||
| `openai-codex` | 提供商前缀 | 通过常规 OpenClaw PI runner 使用 OpenAI Codex OAuth / 订阅路由。 |
|
||||
| `codex` plugin | 插件 | OpenClaw 内置插件，提供原生 Codex app-server 运行时和 `/codex` 聊天控制。 |
|
||||
| `agentRuntime.id: codex` | Agent 运行时 | 为嵌入式轮次强制使用原生 Codex app-server harness。 |
|
||||
| `/codex ...` | 聊天命令集 | 在对话中绑定 / 控制 Codex app-server 线程。 |
|
||||
| `runtime: "acp", agentId: "codex"` | ACP 会话路由 | 通过 ACP/acpx 运行 Codex 的显式回退路径。 |
|
||||
|
||||
这意味着一个配置可以有意同时包含 `openai-codex/*` 和
|
||||
`codex` 插件。当你想通过 PI 使用 Codex OAuth，同时还希望
|
||||
原生 `/codex` 聊天控制可用时，这是有效的。`openclaw doctor` 会对这种
|
||||
组合发出警告，以便你确认这是有意为之；它不会改写该配置。
|
||||
这意味着，一个配置中可以有意同时包含 `openai-codex/*` 和 `codex` plugin。当你希望通过 PI 使用 Codex OAuth，同时又希望可使用原生 `/codex` 聊天控制时，这样做是有效的。`openclaw doctor` 会对这种组合发出警告，以便你确认这是有意为之；它不会重写该配置。
|
||||
|
||||
<Note>
|
||||
GPT-5.5 同时支持通过直接 OpenAI Platform API 密钥访问以及
|
||||
订阅/OAuth 路线使用。对直接 `OPENAI_API_KEY`
|
||||
流量，请使用 `openai/gpt-5.5`；对通过 PI 的 Codex OAuth，请使用
|
||||
`openai-codex/gpt-5.5`；对原生 Codex
|
||||
app-server harness，请使用带 `agentRuntime.id: "codex"` 的 `openai/gpt-5.5`。
|
||||
GPT-5.5 同时支持通过直接 OpenAI Platform API 密钥访问，以及订阅 / OAuth 路由访问。对直接 `OPENAI_API_KEY` 流量，请使用 `openai/gpt-5.5`；对通过 PI 的 Codex OAuth，请使用 `openai-codex/gpt-5.5`；若要使用原生 Codex app-server harness，请使用 `openai/gpt-5.5` 并配合 `agentRuntime.id: "codex"`。
|
||||
</Note>
|
||||
|
||||
<Note>
|
||||
启用 OpenAI 插件，或选择 `openai-codex/*` 模型，
|
||||
并不会启用内置 Codex app-server 插件。OpenClaw 仅在
|
||||
你显式选择原生 Codex harness（`agentRuntime.id: "codex"`）或使用旧版 `codex/*` 模型引用时，
|
||||
才会启用该插件。
|
||||
如果内置 `codex` 插件已启用，但 `openai-codex/*` 仍然通过 PI 解析，
|
||||
`openclaw doctor` 会发出警告，并保持该路线不变。
|
||||
启用 OpenAI plugin，或选择 `openai-codex/*` 模型，并不会启用内置的 Codex app-server plugin。只有在你明确通过 `agentRuntime.id: "codex"` 选择原生 Codex harness，或使用旧版 `codex/*` 模型引用时，OpenClaw 才会启用该插件。
|
||||
如果内置 `codex` plugin 已启用，但 `openai-codex/*` 仍通过 PI 解析，`openclaw doctor` 会发出警告，并保持该路由不变。
|
||||
</Note>
|
||||
|
||||
## OpenClaw 功能覆盖范围
|
||||
|
||||
| OpenAI 能力 | OpenClaw surface | 状态 |
|
||||
| ------------------------- | ---------------------------------------------------------- | --------------------------------------------------- |
|
||||
| 聊天 / Responses | `openai/<model>` model provider | 是 |
|
||||
| Codex 订阅模型 | 带 `openai-codex` OAuth 的 `openai-codex/<model>` | 是 |
|
||||
| Codex app-server harness | 带 `agentRuntime.id: codex` 的 `openai/<model>` | 是 |
|
||||
| 服务端 Web 搜索 | 原生 OpenAI Responses 工具 | 是，启用 Web 搜索且未固定 provider 时可用 |
|
||||
| 图像 | `image_generate` | 是 |
|
||||
| 视频 | `video_generate` | 是 |
|
||||
| 文本转语音 | `messages.tts.provider: "openai"` / `tts` | 是 |
|
||||
| 批量语音转文本 | `tools.media.audio` / 媒体理解 | 是 |
|
||||
| 流式语音转文本 | Voice Call `streaming.provider: "openai"` | 是 |
|
||||
| 实时语音 | Voice Call `realtime.provider: "openai"` / Control UI Talk | 是 |
|
||||
| Embeddings | memory embedding provider | 是 |
|
||||
| OpenAI 能力 | OpenClaw 能力面 | Status |
|
||||
| ------------------------- | ---------------------------------------------------------- | ------------------------------------------------------ |
|
||||
| 聊天 / Responses | `openai/<model>` 模型提供商 | 是 |
|
||||
| Codex 订阅模型 | 带有 `openai-codex` OAuth 的 `openai-codex/<model>` | 是 |
|
||||
| Codex app-server harness | 带有 `agentRuntime.id: codex` 的 `openai/<model>` | 是 |
|
||||
| 服务端 Web 搜索 | 原生 OpenAI Responses 工具 | 是，在启用 Web 搜索且未固定提供商时 |
|
||||
| 图像 | `image_generate` | 是 |
|
||||
| 视频 | `video_generate` | 是 |
|
||||
| 文本转语音 | `messages.tts.provider: "openai"` / `tts` | 是 |
|
||||
| 批量语音转文本 | `tools.media.audio` / 媒体理解 | 是 |
|
||||
| 流式语音转文本 | 语音通话 `streaming.provider: "openai"` | 是 |
|
||||
| 实时语音 | 语音通话 `realtime.provider: "openai"` / Control UI Talk | 是 |
|
||||
| Embeddings | memory embedding provider | 是 |
|
||||
|
||||
## Memory 嵌入
|
||||
## Memory embeddings
|
||||
|
||||
OpenClaw 可以使用 OpenAI，或兼容 OpenAI 的嵌入端点，来为
|
||||
`memory_search` 提供索引和查询嵌入：
|
||||
OpenClaw 可以为 `memory_search` 索引和查询嵌入使用 OpenAI，或兼容 OpenAI 的嵌入端点：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -107,11 +93,7 @@ OpenClaw 可以使用 OpenAI，或兼容 OpenAI 的嵌入端点，来为
|
||||
}
|
||||
```
|
||||
|
||||
对于要求非对称嵌入标签的 OpenAI 兼容端点，请在
|
||||
`memorySearch` 下设置 `queryInputType` 和 `documentInputType`。OpenClaw 会将
|
||||
它们作为 provider 专属的 `input_type` 请求字段转发：查询嵌入使用
|
||||
`queryInputType`；已索引的 memory 分块和批量索引使用
|
||||
`documentInputType`。完整示例参见[Memory 配置参考](/zh-CN/reference/memory-config#provider-specific-config)。
|
||||
对于需要非对称嵌入标签的 OpenAI 兼容端点，请在 `memorySearch` 下设置 `queryInputType` 和 `documentInputType`。OpenClaw 会将它们作为提供商特定的 `input_type` 请求字段转发：查询嵌入使用 `queryInputType`；已索引的记忆分块和批量索引使用 `documentInputType`。完整示例请参阅 [Memory configuration reference](/zh-CN/reference/memory-config#provider-specific-config)。
|
||||
|
||||
## 入门指南
|
||||
|
||||
@ -123,7 +105,7 @@ OpenClaw 可以使用 OpenAI，或兼容 OpenAI 的嵌入端点，来为
|
||||
|
||||
<Steps>
|
||||
<Step title="获取你的 API 密钥">
|
||||
在 [OpenAI Platform 控制台](https://platform.openai.com/api-keys) 中创建或复制一个 API 密钥。
|
||||
在 [OpenAI Platform dashboard](https://platform.openai.com/api-keys) 中创建或复制一个 API 密钥。
|
||||
</Step>
|
||||
<Step title="运行新手引导">
|
||||
```bash
|
||||
@ -143,20 +125,16 @@ OpenClaw 可以使用 OpenAI，或兼容 OpenAI 的嵌入端点，来为
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
### 路线摘要
|
||||
### 路由摘要
|
||||
|
||||
| 模型引用 | 运行时配置 | 路线 | 认证 |
|
||||
| ---------------------- | ------------------------------------------ | -------------------------- | ---------------- |
|
||||
| `openai/gpt-5.5` | 省略 / `agentRuntime.id: "pi"` | 直接 OpenAI Platform API | `OPENAI_API_KEY` |
|
||||
| `openai/gpt-5.4-mini` | 省略 / `agentRuntime.id: "pi"` | 直接 OpenAI Platform API | `OPENAI_API_KEY` |
|
||||
| `openai/gpt-5.5` | `agentRuntime.id: "codex"` | Codex app-server harness | Codex app-server |
|
||||
| 模型引用 | 运行时配置 | 路由 | 认证 |
|
||||
| ---------------------- | -------------------------- | --------------------------- | ---------------- |
|
||||
| `openai/gpt-5.5` | omitted / `agentRuntime.id: "pi"` | 直接 OpenAI Platform API | `OPENAI_API_KEY` |
|
||||
| `openai/gpt-5.4-mini` | omitted / `agentRuntime.id: "pi"` | 直接 OpenAI Platform API | `OPENAI_API_KEY` |
|
||||
| `openai/gpt-5.5` | `agentRuntime.id: "codex"` | Codex app-server harness | Codex app-server |
|
||||
|
||||
<Note>
|
||||
除非你显式强制使用 Codex app-server harness，否则 `openai/*`
|
||||
就是直接的 OpenAI API 密钥路线。对通过
|
||||
默认 PI 运行器使用的 Codex OAuth，请使用 `openai-codex/*`；或者使用带
|
||||
`agentRuntime.id: "codex"` 的 `openai/gpt-5.5` 进行原生 Codex
|
||||
app-server 执行。
|
||||
`openai/*` 是直接 OpenAI API 密钥路由，除非你显式强制使用 Codex app-server harness。对于通过默认 PI runner 的 Codex OAuth，请使用 `openai-codex/*`；若要使用原生 Codex app-server 执行，请使用 `openai/gpt-5.5` 并配合 `agentRuntime.id: "codex"`。
|
||||
</Note>
|
||||
|
||||
### 配置示例
|
||||
@ -169,13 +147,13 @@ OpenClaw 可以使用 OpenAI，或兼容 OpenAI 的嵌入端点，来为
|
||||
```
|
||||
|
||||
<Warning>
|
||||
OpenClaw **不会**暴露 `openai/gpt-5.3-codex-spark`。实时 OpenAI API 请求会拒绝该模型，而当前 Codex 目录也没有暴露它。
|
||||
OpenClaw **不**公开提供 `openai/gpt-5.3-codex-spark`。实时 OpenAI API 请求会拒绝该模型，而当前 Codex 目录也未公开它。
|
||||
</Warning>
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="Codex 订阅">
|
||||
**最适合：** 使用你的 ChatGPT/Codex 订阅，而不是单独的 API 密钥。Codex 云要求使用 ChatGPT 登录。
|
||||
**最适合：** 使用你的 ChatGPT/Codex 订阅，而不是单独的 API 密钥。Codex cloud 需要 ChatGPT 登录。
|
||||
|
||||
<Steps>
|
||||
<Step title="运行 Codex OAuth">
|
||||
@ -189,7 +167,7 @@ OpenClaw 可以使用 OpenAI，或兼容 OpenAI 的嵌入端点，来为
|
||||
openclaw models auth login --provider openai-codex
|
||||
```
|
||||
|
||||
对于无头环境或不适合回调主机的配置，可添加 `--device-code`，改用 ChatGPT 设备码流程登录，而不是本地主机浏览器回调：
|
||||
对于无头环境或不适合回调的设置，可添加 `--device-code`，通过 ChatGPT device-code 流程登录，而不是使用 localhost 浏览器回调：
|
||||
|
||||
```bash
|
||||
openclaw models auth login --provider openai-codex --device-code
|
||||
@ -207,18 +185,17 @@ OpenClaw 可以使用 OpenAI，或兼容 OpenAI 的嵌入端点，来为
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
### 路线摘要
|
||||
### 路由摘要
|
||||
|
||||
| 模型引用 | 运行时配置 | 路线 | 认证 |
|
||||
|-----------|------------|------|------|
|
||||
| `openai-codex/gpt-5.5` | 省略 / `runtime: "pi"` | 通过 PI 使用 ChatGPT/Codex OAuth | Codex 登录 |
|
||||
| `openai-codex/gpt-5.5` | `runtime: "auto"` | 仍然走 PI，除非插件显式声明 `openai-codex` | Codex 登录 |
|
||||
| `openai/gpt-5.5` | `agentRuntime.id: "codex"` | Codex app-server harness | Codex app-server 认证 |
|
||||
| 模型引用 | 运行时配置 | 路由 | 认证 |
|
||||
|-----------|----------------|-------|------|
|
||||
| `openai-codex/gpt-5.5` | omitted / `runtime: "pi"` | 通过 PI 的 ChatGPT/Codex OAuth | Codex 登录 |
|
||||
| `openai-codex/gpt-5.5` | `runtime: "auto"` | 仍为 PI，除非某个插件显式声明 `openai-codex` | Codex 登录 |
|
||||
| `openai/gpt-5.5` | `agentRuntime.id: "codex"` | Codex app-server harness | Codex app-server auth |
|
||||
|
||||
<Note>
|
||||
对认证/profile 命令，继续使用 `openai-codex` provider id。
|
||||
`openai-codex/*` 模型前缀也是通过 PI 使用 Codex OAuth 的显式路线。
|
||||
它不会选择或自动启用内置 Codex app-server harness。
|
||||
对于认证 / 配置文件命令，请继续使用 `openai-codex` provider id。`openai-codex/*` 模型前缀也是通过 PI 的 Codex OAuth 的显式路由。
|
||||
它不会选择或自动启用内置的 Codex app-server harness。
|
||||
</Note>
|
||||
|
||||
### 配置示例
|
||||
@ -230,78 +207,65 @@ OpenClaw 可以使用 OpenAI，或兼容 OpenAI 的嵌入端点，来为
|
||||
```
|
||||
|
||||
<Note>
|
||||
新手引导不再从 `~/.codex` 导入 OAuth 材料。请使用浏览器 OAuth（默认）或上面的设备码流程登录 —— OpenClaw 会在自己的智能体认证存储中管理生成的凭证。
|
||||
新手引导不再从 `~/.codex` 导入 OAuth 材料。请使用浏览器 OAuth（默认）或上面的 device-code 流程登录 —— OpenClaw 会在它自己的智能体认证存储中管理生成的凭证。
|
||||
</Note>
|
||||
|
||||
### 状态指示器
|
||||
### Status 指示器
|
||||
|
||||
聊天中的 `/status` 会显示当前会话激活的是哪个模型运行时。
|
||||
默认 PI harness 会显示为 `Runtime: OpenClaw Pi Default`。当
|
||||
选择内置 Codex app-server harness 时，`/status` 会显示
|
||||
`Runtime: OpenAI Codex`。现有会话会保留其记录的 harness id，因此如果你在更改 `agentRuntime` 后希望 `/status`
|
||||
反映新的 PI/Codex 选择，请使用 `/new` 或 `/reset`。
|
||||
聊天中的 `/status` 会显示当前会话启用了哪个模型运行时。默认的 PI harness 显示为 `Runtime: OpenClaw Pi Default`。选择内置 Codex app-server harness 时，`/status` 会显示 `Runtime: OpenAI Codex`。现有会话会保留其已记录的 harness id，因此如果你在更改 `agentRuntime` 后希望 `/status` 反映新的 PI / Codex 选择，请使用 `/new` 或 `/reset`。
|
||||
|
||||
### Doctor 警告
|
||||
|
||||
如果在选择本标签页中的
|
||||
`openai-codex/*` 路线时启用了内置 `codex` 插件，`openclaw doctor` 会警告该模型
|
||||
仍然通过 PI 解析。如果这正是你想要的订阅认证路线，请保持配置不变。仅当你想要原生 Codex
|
||||
app-server 执行时，才切换到 `openai/<model>` 加
|
||||
`agentRuntime.id: "codex"`。
|
||||
如果在选择此标签页中的 `openai-codex/*` 路由时，内置的 `codex` plugin 也已启用，`openclaw doctor` 会警告该模型仍然通过 PI 解析。如果这是你预期的订阅认证路由，请保持配置不变。只有当你想要原生 Codex app-server 执行时，才切换到 `openai/<model>` 加 `agentRuntime.id: "codex"`。
|
||||
|
||||
### 上下文窗口上限
|
||||
### 上下文窗口上限
|
||||
|
||||
OpenClaw 将模型元数据和运行时上下文上限视为两个独立的值。
|
||||
OpenClaw 将模型元数据和运行时上下文上限视为两个独立的值。
|
||||
|
||||
对于通过 Codex OAuth 使用的 `openai-codex/gpt-5.5`：
|
||||
对于通过 Codex OAuth 的 `openai-codex/gpt-5.5`：
|
||||
|
||||
- 原生 `contextWindow`：`1000000`
|
||||
- 默认运行时 `contextTokens` 上限：`272000`
|
||||
- 原生 `contextWindow`：`1000000`
|
||||
- 默认运行时 `contextTokens` 上限：`272000`
|
||||
|
||||
这个更小的默认上限在实践中具有更好的延迟和质量特性。可通过 `contextTokens` 覆盖：
|
||||
在实践中，较小的默认上限通常具有更好的延迟和质量表现。你可以通过 `contextTokens` 覆盖它：
|
||||
|
||||
```json5
|
||||
{
|
||||
models: {
|
||||
providers: {
|
||||
"openai-codex": {
|
||||
models: [{ id: "gpt-5.5", contextTokens: 160000 }],
|
||||
},
|
||||
},
|
||||
```json5
|
||||
{
|
||||
models: {
|
||||
providers: {
|
||||
"openai-codex": {
|
||||
models: [{ id: "gpt-5.5", contextTokens: 160000 }],
|
||||
},
|
||||
}
|
||||
```
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
<Note>
|
||||
使用 `contextWindow` 声明模型的原生元数据。使用 `contextTokens` 限制运行时上下文预算。
|
||||
</Note>
|
||||
<Note>
|
||||
使用 `contextWindow` 声明模型的原生元数据。使用 `contextTokens` 限制运行时上下文预算。
|
||||
</Note>
|
||||
|
||||
### 目录恢复
|
||||
### 目录恢复
|
||||
|
||||
当上游 Codex 目录中存在 `gpt-5.5` 元数据时，OpenClaw 会使用它。
|
||||
如果实时 Codex 发现结果中缺少 `openai-codex/gpt-5.5` 这一行，而账户
|
||||
已通过认证，OpenClaw 会合成这一 OAuth 模型条目，这样
|
||||
cron、子智能体和已配置的默认模型运行就不会因
|
||||
`Unknown model` 而失败。
|
||||
当上游 Codex 目录元数据中存在 `gpt-5.5` 时，OpenClaw 会使用它。如果实时 Codex 发现未返回 `openai-codex/gpt-5.5` 这一行，但账户已完成认证，OpenClaw 会合成这一 OAuth 模型行，以避免 cron、子智能体和已配置的默认模型运行因 `Unknown model` 而失败。
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
## 图像生成
|
||||
|
||||
内置 `openai` 插件通过 `image_generate` 工具注册图像生成。
|
||||
它通过同一个 `openai/gpt-image-2` 模型引用，同时支持基于 OpenAI API 密钥的图像生成和基于 Codex OAuth 的图像
|
||||
生成。
|
||||
内置的 `openai` plugin 通过 `image_generate` 工具注册图像生成功能。
|
||||
它支持使用同一个 `openai/gpt-image-2` 模型引用，通过 OpenAI API 密钥进行图像生成，以及通过 Codex OAuth 进行图像生成。
|
||||
|
||||
| 能力 | OpenAI API 密钥 | Codex OAuth |
|
||||
| ----------------------- | ---------------------------------- | ------------------------------------- |
|
||||
| 模型引用 | `openai/gpt-image-2` | `openai/gpt-image-2` |
|
||||
| 认证 | `OPENAI_API_KEY` | OpenAI Codex OAuth 登录 |
|
||||
| 传输 | OpenAI Images API | Codex Responses 后端 |
|
||||
| 每次请求最大图像数 | 4 | 4 |
|
||||
| 编辑模式 | 已启用（最多 5 张参考图像） | 已启用（最多 5 张参考图像） |
|
||||
| 尺寸覆盖 | 支持，包括 2K/4K 尺寸 | 支持，包括 2K/4K 尺寸 |
|
||||
| 宽高比 / 分辨率 | 不会转发给 OpenAI Images API | 安全时映射到受支持的尺寸 |
|
||||
| 能力 | OpenAI API 密钥 | Codex OAuth |
|
||||
| ------------------------- | ---------------------------------- | ------------------------------------ |
|
||||
| 模型引用 | `openai/gpt-image-2` | `openai/gpt-image-2` |
|
||||
| 认证 | `OPENAI_API_KEY` | OpenAI Codex OAuth 登录 |
|
||||
| 传输 | OpenAI Images API | Codex Responses 后端 |
|
||||
| 每次请求的最大图像数 | 4 | 4 |
|
||||
| 编辑模式 | 已启用（最多 5 张参考图像） | 已启用（最多 5 张参考图像） |
|
||||
| 尺寸覆盖 | 支持，包括 2K/4K 尺寸 | 支持，包括 2K/4K 尺寸 |
|
||||
| 宽高比 / 分辨率 | 不会转发到 OpenAI Images API | 在安全情况下映射为受支持的尺寸 |
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -314,24 +278,14 @@ OpenClaw 可以使用 OpenAI，或兼容 OpenAI 的嵌入端点，来为
|
||||
```
|
||||
|
||||
<Note>
|
||||
共享工具参数、provider 选择和故障转移行为，参见[图像生成](/zh-CN/tools/image-generation)。
|
||||
有关共享工具参数、提供商选择和故障转移行为，请参阅 [Image Generation](/zh-CN/tools/image-generation)。
|
||||
</Note>
|
||||
|
||||
`gpt-image-2` 是 OpenAI 文生图和图像
|
||||
编辑的默认模型。`gpt-image-1.5`、`gpt-image-1` 和 `gpt-image-1-mini` 仍可作为
|
||||
显式模型覆盖项使用。对透明背景
|
||||
PNG/WebP 输出，请使用 `openai/gpt-image-1.5`；当前 `gpt-image-2` API 会拒绝
|
||||
`background: "transparent"`。
|
||||
`gpt-image-2` 是 OpenAI 文生图和图像编辑的默认模型。`gpt-image-1.5`、`gpt-image-1` 和 `gpt-image-1-mini` 仍可作为显式模型覆盖使用。对于透明背景的 PNG/WebP 输出，请使用 `openai/gpt-image-1.5`；当前的 `gpt-image-2` API 会拒绝 `background: "transparent"`。
|
||||
|
||||
对于透明背景请求，智能体应调用 `image_generate`，并设置
|
||||
`model: "openai/gpt-image-1.5"`、`outputFormat: "png"` 或 `"webp"`，以及
|
||||
`background: "transparent"`；旧版的 `openai.background` provider 选项
|
||||
仍然可用。OpenClaw 还会通过将默认的 `openai/gpt-image-2` 透明背景请求
|
||||
重写为 `gpt-image-1.5`，来保护公开的 OpenAI 和
|
||||
OpenAI Codex OAuth 路线；Azure 和自定义 OpenAI 兼容端点会保留
|
||||
其已配置的 deployment/model 名称。
|
||||
对于透明背景请求，智能体应调用 `image_generate`，并设置 `model: "openai/gpt-image-1.5"`、`outputFormat: "png"` 或 `"webp"`，以及 `background: "transparent"`；旧的 `openai.background` 提供商选项仍然被接受。OpenClaw 还会通过将默认 `openai/gpt-image-2` 的透明背景请求重写为 `gpt-image-1.5`，来保护公共 OpenAI 和 OpenAI Codex OAuth 路由；Azure 和自定义 OpenAI 兼容端点则保留它们已配置的部署 / 模型名称。
|
||||
|
||||
这个设置也可用于无头 CLI 运行：
|
||||
相同设置也适用于无头 CLI 运行：
|
||||
|
||||
```bash
|
||||
openclaw infer image generate \
|
||||
@ -342,19 +296,11 @@ openclaw infer image generate \
|
||||
--json
|
||||
```
|
||||
|
||||
从输入文件开始时，对
|
||||
`openclaw infer image edit` 使用相同的 `--output-format` 和 `--background` 标志。
|
||||
`--openai-background` 仍然作为 OpenAI 专属别名可用。
|
||||
当从输入文件开始时，对 `openclaw infer image edit` 使用相同的 `--output-format` 和 `--background` 标志。
|
||||
`--openai-background` 仍可作为 OpenAI 专用别名使用。
|
||||
|
||||
对于 Codex OAuth 安装，保持使用同一个 `openai/gpt-image-2` 引用。当
|
||||
配置了 `openai-codex` OAuth profile 时，OpenClaw 会解析该已存储的 OAuth
|
||||
访问令牌，并通过 Codex Responses 后端发送图像请求。它
|
||||
不会先尝试 `OPENAI_API_KEY`，也不会为该请求静默回退到 API 密钥。如果你想使用直接的 OpenAI Images API
|
||||
路线，请显式配置 `models.providers.openai`，并提供 API 密钥、
|
||||
自定义 base URL 或 Azure 端点。
|
||||
如果该自定义图像端点位于受信任的 LAN/私有地址上，还请设置
|
||||
`browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true`；如果没有这个显式启用项，
|
||||
OpenClaw 会继续阻止私有/内部 OpenAI 兼容图像端点。
|
||||
对于 Codex OAuth 安装，请继续使用相同的 `openai/gpt-image-2` 引用。当配置了 `openai-codex` OAuth 配置文件时，OpenClaw 会解析该已存储的 OAuth 访问令牌，并通过 Codex Responses 后端发送图像请求。它不会先尝试 `OPENAI_API_KEY`，也不会在该请求中静默回退到 API 密钥。如果你想改用直接 OpenAI Images API 路由，请显式配置 `models.providers.openai`，并提供 API 密钥、自定义 base URL 或 Azure 端点。
|
||||
如果该自定义图像端点位于受信任的 LAN / 私有地址上，还要设置 `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true`；若没有这一显式启用项，OpenClaw 会继续阻止私有 / 内部的 OpenAI 兼容图像端点。
|
||||
|
||||
生成：
|
||||
|
||||
@ -376,15 +322,15 @@ OpenClaw 会继续阻止私有/内部 OpenAI 兼容图像端点。
|
||||
|
||||
## 视频生成
|
||||
|
||||
内置 `openai` 插件通过 `video_generate` 工具注册视频生成。
|
||||
内置的 `openai` plugin 通过 `video_generate` 工具注册视频生成功能。
|
||||
|
||||
| 能力 | 值 |
|
||||
| 能力 | 值 |
|
||||
| ---------------- | --------------------------------------------------------------------------------- |
|
||||
| 默认模型 | `openai/sora-2` |
|
||||
| 模式 | 文本生成视频、图像生成视频、单视频编辑 |
|
||||
| 参考输入 | 1 张图像或 1 段视频 |
|
||||
| 尺寸覆盖 | 支持 |
|
||||
| 其他覆盖 | `aspectRatio`、`resolution`、`audio`、`watermark` 会被忽略，并附带工具警告 |
|
||||
| 默认模型 | `openai/sora-2` |
|
||||
| 模式 | 文生视频、图生视频、单视频编辑 |
|
||||
| 参考输入 | 1 张图像或 1 个视频 |
|
||||
| 尺寸覆盖 | 支持 |
|
||||
| 其他覆盖 | `aspectRatio`、`resolution`、`audio`、`watermark` 会被忽略，并产生工具警告 |
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -397,22 +343,22 @@ OpenClaw 会继续阻止私有/内部 OpenAI 兼容图像端点。
|
||||
```
|
||||
|
||||
<Note>
|
||||
共享工具参数、provider 选择和故障转移行为，参见[视频生成](/zh-CN/tools/video-generation)。
|
||||
有关共享工具参数、提供商选择和故障转移行为，请参阅 [Video Generation](/zh-CN/tools/video-generation)。
|
||||
</Note>
|
||||
|
||||
## GPT-5 提示词贡献
|
||||
|
||||
OpenClaw 会为跨 provider 的 GPT-5 系列运行添加一个共享 GPT-5 提示词贡献。它按模型 id 应用，因此 `openai-codex/gpt-5.5`、`openai/gpt-5.5`、`openrouter/openai/gpt-5.5`、`opencode/gpt-5.5` 以及其他兼容的 GPT-5 引用都会收到相同的覆盖层。较旧的 GPT-4.x 模型则不会。
|
||||
OpenClaw 为跨提供商的 GPT-5 系列运行添加了一个共享的 GPT-5 提示词贡献。它按模型 id 生效，因此 `openai-codex/gpt-5.5`、`openai/gpt-5.5`、`openrouter/openai/gpt-5.5`、`opencode/gpt-5.5` 以及其他兼容的 GPT-5 引用都会接收相同的覆盖层。较旧的 GPT-4.x 模型则不会。
|
||||
|
||||
内置的原生 Codex harness 通过 Codex app-server 开发者指令使用相同的 GPT-5 行为和 heartbeat 覆盖层，因此即使 Codex 接管了 harness 提示词的其余部分，那些通过 `agentRuntime.id: "codex"` 强制使用的 `openai/gpt-5.x` 会话，仍会保留相同的后续执行和主动 heartbeat 指导。
|
||||
内置的原生 Codex harness 通过 Codex app-server 开发者指令使用相同的 GPT-5 行为和心跳覆盖层，因此，强制通过 `agentRuntime.id: "codex"` 的 `openai/gpt-5.x` 会话，即使其余 harness 提示词由 Codex 控制，也会保留相同的跟进行为和主动心跳指导。
|
||||
|
||||
GPT-5 贡献会为 persona 持续性、执行安全、工具纪律、输出形态、完成检查和验证添加一个带标签的行为契约。渠道专属的回复和静默消息行为仍保留在共享的 OpenClaw 系统提示词和出站投递策略中。GPT-5 指导对匹配模型始终启用。友好交互风格层是独立且可配置的。
|
||||
GPT-5 贡献添加了一个带标签的行为契约，用于约束 persona 持续性、执行安全、工具纪律、输出形态、完成检查和验证。渠道特定的回复行为和静默消息行为仍保留在共享的 OpenClaw 系统提示词和出站传递策略中。对于匹配的模型，GPT-5 指导始终启用。友好交互风格层是独立且可配置的。
|
||||
|
||||
| 值 | 效果 |
|
||||
| ---------------------- | ------------------------------------- |
|
||||
| `"friendly"`（默认） | 启用友好交互风格层 |
|
||||
| `"on"` | `"friendly"` 的别名 |
|
||||
| `"off"` | 仅禁用友好风格层 |
|
||||
| 值 | 效果 |
|
||||
| ---------------------- | ------------------------------------------- |
|
||||
| `"friendly"`（默认） | 启用友好交互风格层 |
|
||||
| `"on"` | `"friendly"` 的别名 |
|
||||
| `"off"` | 仅禁用友好风格层 |
|
||||
|
||||
<Tabs>
|
||||
<Tab title="配置">
|
||||
@ -436,18 +382,18 @@ GPT-5 贡献会为 persona 持续性、执行安全、工具纪律、输出形
|
||||
</Tabs>
|
||||
|
||||
<Tip>
|
||||
这些值在运行时不区分大小写，因此 `"Off"` 和 `"off"` 都会禁用友好风格层。
|
||||
运行时对值不区分大小写，因此 `"Off"` 和 `"off"` 都会禁用友好风格层。
|
||||
</Tip>
|
||||
|
||||
<Note>
|
||||
当未设置共享的 `agents.defaults.promptOverlays.gpt5.personality` 配置时，旧版 `plugins.entries.openai.config.personality` 仍会作为兼容性回退项读取。
|
||||
当未设置共享的 `agents.defaults.promptOverlays.gpt5.personality` 时，旧版 `plugins.entries.openai.config.personality` 仍会作为兼容性回退被读取。
|
||||
</Note>
|
||||
|
||||
## 语音和语音处理
|
||||
## 语音与语音处理
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="语音合成（TTS）">
|
||||
内置 `openai` 插件为 `messages.tts` surface 注册语音合成。
|
||||
内置的 `openai` plugin 为 `messages.tts` 能力面注册了语音合成功能。
|
||||
|
||||
| 设置 | 配置路径 | 默认值 |
|
||||
|---------|------------|---------|
|
||||
@ -474,23 +420,20 @@ GPT-5 贡献会为 persona 持续性、执行安全、工具纪律、输出形
|
||||
```
|
||||
|
||||
<Note>
|
||||
设置 `OPENAI_TTS_BASE_URL` 可覆盖 TTS base URL，而不影响聊天 API 端点。
|
||||
设置 `OPENAI_TTS_BASE_URL` 可覆盖 TTS 的 base URL，而不会影响聊天 API 端点。
|
||||
</Note>
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="语音转文本">
|
||||
内置 `openai` 插件通过
|
||||
OpenClaw 的媒体理解转录 surface 注册批量语音转文本。
|
||||
内置的 `openai` plugin 通过 OpenClaw 的媒体理解转录能力面注册了批量语音转文本功能。
|
||||
|
||||
- 默认模型：`gpt-4o-transcribe`
|
||||
- 端点：OpenAI REST `/v1/audio/transcriptions`
|
||||
- 输入路径：multipart 音频文件上传
|
||||
- 在 OpenClaw 中，只要入站音频转录使用
|
||||
`tools.media.audio`，就支持该能力，包括 Discord 语音频道片段和渠道
|
||||
音频附件
|
||||
- 在 OpenClaw 中，凡是入站音频转录使用 `tools.media.audio` 的地方都支持，包括 Discord 语音频道片段和渠道音频附件
|
||||
|
||||
要强制对入站音频转录使用 OpenAI：
|
||||
若要为入站音频转录强制使用 OpenAI：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -510,31 +453,30 @@ GPT-5 贡献会为 persona 持续性、执行安全、工具纪律、输出形
|
||||
}
|
||||
```
|
||||
|
||||
当共享音频媒体配置或按调用转录请求
|
||||
提供语言和提示词提示时，它们会被转发给 OpenAI。
|
||||
当共享音频媒体配置或按调用的转录请求提供了语言和提示词提示时，OpenClaw 会将它们转发给 OpenAI。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="实时转录">
|
||||
内置 `openai` 插件为 Voice Call 插件注册实时转录。
|
||||
内置的 `openai` plugin 为 Voice Call 插件注册了实时转录功能。
|
||||
|
||||
| 设置 | 配置路径 | 默认值 |
|
||||
|---------|------------|---------|
|
||||
| 模型 | `plugins.entries.voice-call.config.streaming.providers.openai.model` | `gpt-4o-transcribe` |
|
||||
| 语言 | `...openai.language` | （未设置） |
|
||||
| 提示词 | `...openai.prompt` | （未设置） |
|
||||
| 静默时长 | `...openai.silenceDurationMs` | `800` |
|
||||
| 静音时长 | `...openai.silenceDurationMs` | `800` |
|
||||
| VAD 阈值 | `...openai.vadThreshold` | `0.5` |
|
||||
| API 密钥 | `...openai.apiKey` | 回退到 `OPENAI_API_KEY` |
|
||||
|
||||
<Note>
|
||||
使用到 `wss://api.openai.com/v1/realtime` 的 WebSocket 连接，以及 G.711 u-law（`g711_ulaw` / `audio/pcmu`）音频。这个流式 provider 用于 Voice Call 的实时转录路径；Discord 语音目前仍是录制短片段，并改用批量 `tools.media.audio` 转录路径。
|
||||
使用到 `wss://api.openai.com/v1/realtime` 的 WebSocket 连接，并采用 G.711 u-law（`g711_ulaw` / `audio/pcmu`）音频。这个流式提供商用于 Voice Call 的实时转录路径；Discord 语音当前仍会录制短片段，并改用批量 `tools.media.audio` 转录路径。
|
||||
</Note>
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="实时语音">
|
||||
内置 `openai` 插件为 Voice Call 插件注册实时语音功能。
|
||||
内置的 `openai` plugin 为 Voice Call 插件注册了实时语音功能。
|
||||
|
||||
| 设置 | 配置路径 | 默认值 |
|
||||
|---------|------------|---------|
|
||||
@ -542,11 +484,17 @@ GPT-5 贡献会为 persona 持续性、执行安全、工具纪律、输出形
|
||||
| 语音 | `...openai.voice` | `alloy` |
|
||||
| Temperature | `...openai.temperature` | `0.8` |
|
||||
| VAD 阈值 | `...openai.vadThreshold` | `0.5` |
|
||||
| 静默时长 | `...openai.silenceDurationMs` | `500` |
|
||||
| 静音时长 | `...openai.silenceDurationMs` | `500` |
|
||||
| API 密钥 | `...openai.apiKey` | 回退到 `OPENAI_API_KEY` |
|
||||
|
||||
<Note>
|
||||
通过 `azureEndpoint` 和 `azureDeployment` 配置键支持 Azure OpenAI。支持双向工具调用。使用 G.711 u-law 音频格式。
|
||||
通过 `azureEndpoint` 和 `azureDeployment` 配置键支持 Azure OpenAI，用于后端实时桥接。支持双向工具调用。使用 G.711 u-law 音频格式。
|
||||
</Note>
|
||||
|
||||
<Note>
|
||||
Control UI Talk 使用 OpenAI 浏览器实时会话、由 Gateway 网关签发的临时客户端密钥，以及针对 OpenAI Realtime API 的浏览器直连 WebRTC SDP 交换。
|
||||
维护者可使用 `OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts` 进行实时验证；
|
||||
OpenAI 这一段会在 Node 中签发客户端密钥，使用伪造的麦克风媒体生成浏览器 SDP offer，将其提交给 OpenAI，并在不记录密钥的情况下应用 SDP answer。
|
||||
</Note>
|
||||
|
||||
</Accordion>
|
||||
@ -554,28 +502,23 @@ GPT-5 贡献会为 persona 持续性、执行安全、工具纪律、输出形
|
||||
|
||||
## Azure OpenAI 端点
|
||||
|
||||
内置 `openai` provider 可以通过覆盖 base URL 来定位 Azure OpenAI 资源以进行图像
|
||||
生成。在图像生成路径上，OpenClaw 会
|
||||
检测 `models.providers.openai.baseUrl` 上的 Azure 主机名，并自动切换到
|
||||
Azure 的请求格式。
|
||||
内置的 `openai` provider 可以通过覆盖 base URL，将图像生成请求定向到 Azure OpenAI 资源。在图像生成路径上，OpenClaw 会检测 `models.providers.openai.baseUrl` 上的 Azure 主机名，并自动切换为 Azure 的请求格式。
|
||||
|
||||
<Note>
|
||||
实时语音使用单独的配置路径
|
||||
（`plugins.entries.voice-call.config.realtime.providers.openai.azureEndpoint`），
|
||||
不受 `models.providers.openai.baseUrl` 影响。其 Azure
|
||||
设置参见[语音和语音处理](#voice-and-speech)下的**实时
|
||||
语音**折叠面板。
|
||||
不受 `models.providers.openai.baseUrl` 影响。有关其 Azure 设置，请参阅 [语音与语音处理](#voice-and-speech) 下的 **实时语音** 折叠项。
|
||||
</Note>
|
||||
|
||||
在以下情况下使用 Azure OpenAI：
|
||||
|
||||
- 你已经拥有 Azure OpenAI 订阅、配额或企业协议
|
||||
- 你需要 Azure 提供的区域数据驻留或合规控制
|
||||
- 你希望将流量保留在现有的 Azure 租户内
|
||||
- 你希望将流量保留在现有 Azure 租户内
|
||||
|
||||
### 配置
|
||||
|
||||
对于通过内置 `openai` provider 使用 Azure 图像生成，请将
|
||||
若要通过内置的 `openai` provider 使用 Azure 进行图像生成，请将
|
||||
`models.providers.openai.baseUrl` 指向你的 Azure 资源，并将 `apiKey` 设置为
|
||||
Azure OpenAI 密钥（而不是 OpenAI Platform 密钥）：
|
||||
|
||||
@ -592,8 +535,7 @@ Azure OpenAI 密钥（而不是 OpenAI Platform 密钥）：
|
||||
}
|
||||
```
|
||||
|
||||
OpenClaw 会识别以下 Azure 主机后缀，用于 Azure 图像生成
|
||||
路线：
|
||||
OpenClaw 会识别以下 Azure 主机后缀，以启用 Azure 图像生成路由：
|
||||
|
||||
- `*.openai.azure.com`
|
||||
- `*.services.ai.azure.com`
|
||||
@ -601,91 +543,86 @@ OpenClaw 会识别以下 Azure 主机后缀，用于 Azure 图像生成
|
||||
|
||||
对于发往已识别 Azure 主机的图像生成请求，OpenClaw 会：
|
||||
|
||||
- 发送 `api-key` 请求头，而不是 `Authorization: Bearer`
|
||||
- 使用以 deployment 为作用域的路径（`/openai/deployments/{deployment}/...`）
|
||||
- 发送 `api-key` 头，而不是 `Authorization: Bearer`
|
||||
- 使用以部署为作用域的路径（`/openai/deployments/{deployment}/...`）
|
||||
- 为每个请求追加 `?api-version=...`
|
||||
- 对 Azure 图像生成调用使用默认 600 秒请求超时。
|
||||
按调用设置的 `timeoutMs` 仍会覆盖这个默认值。
|
||||
每次调用的 `timeoutMs` 值仍会覆盖此默认值。
|
||||
|
||||
其他 base URL（公开 OpenAI、OpenAI 兼容代理）会保留标准的
|
||||
其他 base URL（公共 OpenAI、OpenAI 兼容代理）会继续使用标准的
|
||||
OpenAI 图像请求格式。
|
||||
|
||||
<Note>
|
||||
`openai` provider 图像生成路径的 Azure 路由要求
|
||||
OpenClaw 2026.4.22 或更高版本。更早版本会把任何自定义
|
||||
`openai.baseUrl` 当作公开 OpenAI 端点处理，并且会在 Azure
|
||||
图像 deployment 上失败。
|
||||
`openai` provider 的 Azure 图像生成路由需要
|
||||
OpenClaw 2026.4.22 或更高版本。更早版本会将任何自定义
|
||||
`openai.baseUrl` 视为公共 OpenAI 端点，从而在 Azure 图像部署上失败。
|
||||
</Note>
|
||||
|
||||
### API 版本
|
||||
|
||||
设置 `AZURE_OPENAI_API_VERSION` 可为 Azure 图像生成路径固定特定的 Azure 预览版或 GA 版本：
|
||||
设置 `AZURE_OPENAI_API_VERSION` 可为 Azure 图像生成路径固定特定的
|
||||
Azure 预览版或正式版版本：
|
||||
|
||||
```bash
|
||||
export AZURE_OPENAI_API_VERSION="2024-12-01-preview"
|
||||
```
|
||||
|
||||
当该环境变量未设置时，默认值为 `2024-12-01-preview`。
|
||||
当该变量未设置时，默认值为 `2024-12-01-preview`。
|
||||
|
||||
### 模型名称就是 deployment 名称
|
||||
### 模型名称就是部署名称
|
||||
|
||||
Azure OpenAI 会将模型绑定到 deployment。对于通过内置 `openai` provider 路由的 Azure 图像生成请求，OpenClaw 中的 `model` 字段
|
||||
必须是你在 Azure 门户中配置的**Azure deployment 名称**，而不是
|
||||
公开 OpenAI 模型 id。
|
||||
Azure OpenAI 将模型绑定到部署。对于通过内置 `openai` provider 路由的 Azure 图像生成请求，OpenClaw 中的 `model` 字段必须是你在 Azure 门户中配置的 **Azure 部署名称**，而不是公共 OpenAI 模型 id。
|
||||
|
||||
如果你创建了一个名为 `gpt-image-2-prod`、服务于 `gpt-image-2` 的 deployment：
|
||||
如果你创建了一个名为 `gpt-image-2-prod` 的部署来提供 `gpt-image-2`：
|
||||
|
||||
```
|
||||
/tool image_generate model=openai/gpt-image-2-prod prompt="A clean poster" size=1024x1024 count=1
|
||||
```
|
||||
|
||||
同样的 deployment 名称规则也适用于通过内置 `openai` provider 路由的
|
||||
图像生成调用。
|
||||
同样的部署名称规则也适用于通过内置 `openai` provider 路由的图像生成调用。
|
||||
|
||||
### 区域可用性
|
||||
|
||||
Azure 图像生成目前仅在部分区域
|
||||
可用（例如 `eastus2`、`swedencentral`、`polandcentral`、`westus3`、
|
||||
`uaenorth`）。在创建
|
||||
deployment 之前，请查看 Microsoft 当前的区域列表，并确认你的区域提供特定模型。
|
||||
Azure 图像生成目前仅在部分区域可用
|
||||
（例如 `eastus2`、`swedencentral`、`polandcentral`、`westus3`、
|
||||
`uaenorth`）。创建部署前，请先查看 Microsoft 最新的区域列表，并确认你的区域中提供该特定模型。
|
||||
|
||||
### 参数差异
|
||||
|
||||
Azure OpenAI 和公开 OpenAI 并不总是接受相同的图像参数。
|
||||
Azure 可能会拒绝公开 OpenAI 允许的选项（例如某些
|
||||
`background` 在 `gpt-image-2` 上的取值），或者仅在特定模型版本上提供这些选项。这些差异来自 Azure 和底层模型，而不是
|
||||
Azure OpenAI 和公共 OpenAI 并不总是接受相同的图像参数。
|
||||
Azure 可能会拒绝公共 OpenAI 允许的某些选项（例如
|
||||
`gpt-image-2` 上的某些 `background` 值），或者仅在特定模型版本上提供这些选项。这些差异来自 Azure 和底层模型，而不是
|
||||
OpenClaw。如果 Azure 请求因验证错误而失败，请在
|
||||
Azure 门户中检查你的特定 deployment 和 API 版本所支持的参数集。
|
||||
Azure 门户中检查你的具体部署和 API 版本所支持的参数集。
|
||||
|
||||
<Note>
|
||||
Azure OpenAI 使用原生传输和兼容行为，但不会接收
|
||||
OpenClaw 的隐藏归因请求头——参见[高级配置](#advanced-configuration)下的**原生与 OpenAI 兼容
|
||||
路线**折叠面板。
|
||||
OpenClaw 的隐藏归因头 —— 请参阅 [高级配置](#advanced-configuration) 下的 **原生 vs OpenAI-compatible routes** 折叠项。
|
||||
|
||||
对于 Azure 上的聊天或 Responses 流量（除图像生成之外），请使用
|
||||
新手引导流程或专用 Azure provider 配置——仅设置 `openai.baseUrl`
|
||||
不会自动采用 Azure 的 API/认证格式。另有一个独立的
|
||||
`azure-openai-responses/*` provider；参见
|
||||
下方的“服务端压缩”折叠面板。
|
||||
新手引导流程或专用的 Azure provider 配置 —— 仅设置
|
||||
`openai.baseUrl` 不会启用 Azure API / 认证格式。另有一个独立的
|
||||
`azure-openai-responses/*` provider；请参阅下方的
|
||||
服务端压缩折叠项。
|
||||
</Note>
|
||||
|
||||
## 高级配置
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="传输（WebSocket 与 SSE）">
|
||||
OpenClaw 对 `openai/*` 和 `openai-codex/*` 都采用 WebSocket 优先并回退到 SSE（`"auto"`）。
|
||||
<Accordion title="传输方式（WebSocket vs SSE）">
|
||||
OpenClaw 对 `openai/*` 和 `openai-codex/*` 都使用 WebSocket 优先、SSE 回退（`"auto"`）。
|
||||
|
||||
在 `"auto"` 模式下，OpenClaw 会：
|
||||
- 在回退到 SSE 之前，对一次早期 WebSocket 失败进行重试
|
||||
- 失败后，将 WebSocket 标记为降级状态约 60 秒，并在冷却期间使用 SSE
|
||||
- 为重试和重连附加稳定的会话与轮次身份请求头
|
||||
- 在不同传输变体之间标准化用量计数器（`input_tokens` / `prompt_tokens`）
|
||||
- 在回退到 SSE 之前重试一次早期 WebSocket 失败
|
||||
- 失败后将 WebSocket 标记为降级约 60 秒，并在冷却期间使用 SSE
|
||||
- 为重试和重连附加稳定的会话与轮次身份头
|
||||
- 统一不同传输变体下的用量计数器（`input_tokens` / `prompt_tokens`）
|
||||
|
||||
| 值 | 行为 |
|
||||
|-------|----------|
|
||||
| `"auto"`（默认） | WebSocket 优先，回退到 SSE |
|
||||
| `"sse"` | 仅强制使用 SSE |
|
||||
| `"websocket"` | 仅强制使用 WebSocket |
|
||||
| `"auto"`（默认） | WebSocket 优先，SSE 回退 |
|
||||
| `"sse"` | 强制仅使用 SSE |
|
||||
| `"websocket"` | 强制仅使用 WebSocket |
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -731,12 +668,12 @@ OpenClaw 的隐藏归因请求头——参见[高级配置](#advanced-configurat
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="快速模式">
|
||||
OpenClaw 为 `openai/*` 和 `openai-codex/*` 暴露了一个共享的快速模式开关：
|
||||
OpenClaw 为 `openai/*` 和 `openai-codex/*` 提供了共享的快速模式开关：
|
||||
|
||||
- **聊天/UI：** `/fast status|on|off`
|
||||
- **聊天 / UI：** `/fast status|on|off`
|
||||
- **配置：** `agents.defaults.models["<provider>/<model>"].params.fastMode`
|
||||
|
||||
启用后，OpenClaw 会将快速模式映射为 OpenAI 优先处理（`service_tier = "priority"`）。现有 `service_tier` 值会被保留，快速模式不会改写 `reasoning` 或 `text.verbosity`。
|
||||
启用后，OpenClaw 会将快速模式映射到 OpenAI 的优先处理（`service_tier = "priority"`）。现有的 `service_tier` 值会被保留，快速模式不会重写 `reasoning` 或 `text.verbosity`。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -751,13 +688,13 @@ OpenClaw 的隐藏归因请求头——参见[高级配置](#advanced-configurat
|
||||
```
|
||||
|
||||
<Note>
|
||||
会话覆盖优先于配置。在会话 UI 中清除会话覆盖后，会话将恢复到配置的默认值。
|
||||
会话级覆盖优先于配置。在 Sessions UI 中清除会话覆盖后，会话将恢复为配置的默认值。
|
||||
</Note>
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="优先处理（service_tier）">
|
||||
OpenAI 的 API 通过 `service_tier` 暴露优先处理。你可以在 OpenClaw 中按模型设置它：
|
||||
OpenAI 的 API 通过 `service_tier` 提供优先处理。你可以在 OpenClaw 中按模型设置它：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -774,23 +711,23 @@ OpenClaw 的隐藏归因请求头——参见[高级配置](#advanced-configurat
|
||||
支持的值：`auto`、`default`、`flex`、`priority`。
|
||||
|
||||
<Warning>
|
||||
`serviceTier` 仅会被转发到原生 OpenAI 端点（`api.openai.com`）和原生 Codex 端点（`chatgpt.com/backend-api`）。如果你通过代理路由任一 provider，OpenClaw 会保持 `service_tier` 不变。
|
||||
`serviceTier` 仅会转发到原生 OpenAI 端点（`api.openai.com`）和原生 Codex 端点（`chatgpt.com/backend-api`）。如果你通过代理路由任一 provider，OpenClaw 会保持 `service_tier` 原样不变。
|
||||
</Warning>
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="服务端压缩（Responses API）">
|
||||
对于直接 OpenAI Responses 模型（`api.openai.com` 上的 `openai/*`），OpenAI 插件的 Pi-harness 流封装器会自动启用服务端压缩：
|
||||
对于直接 OpenAI Responses 模型（`api.openai.com` 上的 `openai/*`），OpenAI plugin 的 Pi harness 流包装器会自动启用服务端压缩：
|
||||
|
||||
- 强制 `store: true`（除非模型兼容层设置了 `supportsStore: false`）
|
||||
- 强制设置 `store: true`（除非模型兼容性设置 `supportsStore: false`）
|
||||
- 注入 `context_management: [{ type: "compaction", compact_threshold: ... }]`
|
||||
- 默认 `compact_threshold`：`contextWindow` 的 70%（不可用时为 `80000`）
|
||||
- 默认 `compact_threshold`：`contextWindow` 的 70%（若不可用则为 `80000`）
|
||||
|
||||
这适用于内置 Pi harness 路径，也适用于嵌入式运行所使用的 OpenAI provider 钩子。原生 Codex app-server harness 通过 Codex 管理自己的上下文，并通过 `agents.defaults.agentRuntime.id` 单独配置。
|
||||
这适用于内置 Pi harness 路径，也适用于嵌入式运行使用的 OpenAI provider 钩子。原生 Codex app-server harness 通过 Codex 自行管理上下文，并通过 `agents.defaults.agentRuntime.id` 单独配置。
|
||||
|
||||
<Tabs>
|
||||
<Tab title="显式启用">
|
||||
对 Azure OpenAI Responses 之类的兼容端点很有用：
|
||||
适用于 Azure OpenAI Responses 等兼容端点：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -842,7 +779,7 @@ OpenClaw 的隐藏归因请求头——参见[高级配置](#advanced-configurat
|
||||
</Tabs>
|
||||
|
||||
<Note>
|
||||
`responsesServerCompaction` 仅控制 `context_management` 注入。直接 OpenAI Responses 模型仍会强制 `store: true`，除非兼容层将 `supportsStore` 设为 `false`。
|
||||
`responsesServerCompaction` 仅控制 `context_management` 的注入。直接 OpenAI Responses 模型仍会强制设置 `store: true`，除非兼容性配置将 `supportsStore` 设为 `false`。
|
||||
</Note>
|
||||
|
||||
</Accordion>
|
||||
@ -861,35 +798,35 @@ OpenClaw 的隐藏归因请求头——参见[高级配置](#advanced-configurat
|
||||
```
|
||||
|
||||
使用 `strict-agentic` 时，OpenClaw 会：
|
||||
- 不再将仅有计划的轮次视为在有可用工具操作时的成功进展
|
||||
- 使用“立即行动”的引导重试该轮
|
||||
- 对于实质性工作自动启用 `update_plan`
|
||||
- 如果模型持续只做计划而不行动，则显式暴露阻塞状态
|
||||
- 当有可用工具操作时，不再将仅计划轮次视为成功进展
|
||||
- 通过“立即行动”的引导重试该轮次
|
||||
- 对于实质性工作，自动启用 `update_plan`
|
||||
- 如果模型持续规划但不执行，则显式显示阻塞状态
|
||||
|
||||
<Note>
|
||||
仅作用于 OpenAI 和 Codex GPT-5 系列运行。其他 provider 和较早模型系列保持默认行为。
|
||||
仅适用于 OpenAI 和 Codex 的 GPT-5 系列运行。其他 provider 和较旧的模型家族保持默认行为。
|
||||
</Note>
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="原生与 OpenAI 兼容路线">
|
||||
OpenClaw 对直接 OpenAI、Codex 和 Azure OpenAI 端点的处理方式，与通用 OpenAI 兼容 `/v1` 代理不同：
|
||||
<Accordion title="原生 vs OpenAI-compatible 路由">
|
||||
OpenClaw 会区别对待直接 OpenAI、Codex 和 Azure OpenAI 端点，以及通用的 OpenAI-compatible `/v1` 代理：
|
||||
|
||||
**原生路线**（`openai/*`、Azure OpenAI）：
|
||||
**原生路由**（`openai/*`、Azure OpenAI）：
|
||||
- 仅对支持 OpenAI `none` effort 的模型保留 `reasoning: { effort: "none" }`
|
||||
- 对会拒绝 `reasoning.effort: "none"` 的模型或代理省略禁用的 reasoning
|
||||
- 默认将工具 schema 设为严格模式
|
||||
- 仅在已验证的原生主机上附加隐藏归因请求头
|
||||
- 保留 OpenAI 专属请求格式（`service_tier`、`store`、reasoning 兼容层、提示词缓存提示）
|
||||
- 仅在已验证的原生主机上附加隐藏归因头
|
||||
- 保留 OpenAI 专用请求格式（`service_tier`、`store`、reasoning 兼容性、prompt-cache 提示）
|
||||
|
||||
**代理/兼容路线：**
|
||||
**代理 / 兼容路由：**
|
||||
- 使用更宽松的兼容行为
|
||||
- 从非原生 `openai-completions` 负载中移除 Completions `store`
|
||||
- 接受面向 OpenAI 兼容 Completions 代理的高级 `params.extra_body`/`params.extraBody` 透传 JSON
|
||||
- 接受适用于 vLLM 等 OpenAI 兼容 Completions 代理的 `params.chat_template_kwargs`
|
||||
- 不强制严格工具 schema 或原生专用请求头
|
||||
- 从非原生 `openai-completions` 负载中剥离 Completions `store`
|
||||
- 为 OpenAI-compatible Completions 代理接受高级 `params.extra_body` / `params.extraBody` 透传 JSON
|
||||
- 为 OpenAI-compatible Completions 代理（如 vLLM）接受 `params.chat_template_kwargs`
|
||||
- 不会强制使用严格工具 schema 或原生专用头
|
||||
|
||||
Azure OpenAI 使用原生传输和兼容行为，但不会接收隐藏的归因请求头。
|
||||
Azure OpenAI 使用原生传输和兼容行为，但不会接收隐藏归因头。
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@ -898,13 +835,13 @@ OpenClaw 的隐藏归因请求头——参见[高级配置](#advanced-configurat
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="模型选择" href="/zh-CN/concepts/model-providers" icon="layers">
|
||||
选择 provider、模型引用和故障转移行为。
|
||||
选择提供商、模型引用和故障转移行为。
|
||||
</Card>
|
||||
<Card title="图像生成" href="/zh-CN/tools/image-generation" icon="image">
|
||||
共享图像工具参数和 provider 选择。
|
||||
共享图像工具参数和提供商选择。
|
||||
</Card>
|
||||
<Card title="视频生成" href="/zh-CN/tools/video-generation" icon="video">
|
||||
共享视频工具参数和 provider 选择。
|
||||
共享视频工具参数和提供商选择。
|
||||
</Card>
|
||||
<Card title="OAuth 和认证" href="/zh-CN/gateway/authentication" icon="key">
|
||||
认证细节和凭证复用规则。
|
||||
|
||||
@ -5,22 +5,22 @@ read_when:
|
||||
- 你想要调整混合搜索、MMR 或时间衰减参数
|
||||
- 你想要启用多模态 Memory 索引
|
||||
sidebarTitle: Memory config
|
||||
summary: Memory 搜索、嵌入提供商、QMD、混合搜索和多模态索引的所有配置选项
|
||||
summary: Memory 搜索、嵌入提供商、QMD、混合搜索和多模态索引的所有配置项
|
||||
title: Memory 配置参考
|
||||
x-i18n:
|
||||
generated_at: "2026-04-27T13:13:03Z"
|
||||
generated_at: "2026-04-27T13:31:48Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: e063a62b44b7d4fa2df017301cf675678ab71a65f53c78af85f0aa925bb79277
|
||||
source_hash: fe0810e389ad4e8eb4671ea64eb2211887700684b4b781992fe184dc12a958d2
|
||||
source_path: reference/memory-config.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
此页面列出了 OpenClaw Memory 搜索的每一个配置选项。概念性概览请参见：
|
||||
此页面列出了 OpenClaw Memory 搜索的每一个配置项。有关概念性概览，请参阅：
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Memory 概览" href="/zh-CN/concepts/memory">
|
||||
Memory 的工作方式。
|
||||
Memory 的工作原理。
|
||||
</Card>
|
||||
<Card title="内置引擎" href="/zh-CN/concepts/memory-builtin">
|
||||
默认的 SQLite 后端。
|
||||
@ -29,36 +29,36 @@ x-i18n:
|
||||
本地优先的 sidecar。
|
||||
</Card>
|
||||
<Card title="Memory 搜索" href="/zh-CN/concepts/memory-search">
|
||||
搜索管线与调优。
|
||||
搜索流水线与调优。
|
||||
</Card>
|
||||
<Card title="活跃 Memory" href="/zh-CN/concepts/active-memory">
|
||||
<Card title="Active memory" href="/zh-CN/concepts/active-memory">
|
||||
用于交互式会话的 Memory 子智能体。
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
除非另有说明，所有 Memory 搜索设置都位于 `openclaw.json` 的 `agents.defaults.memorySearch` 下。
|
||||
除非另有说明，所有 Memory 搜索设置都位于 `openclaw.json` 中的 `agents.defaults.memorySearch` 下。
|
||||
|
||||
<Note>
|
||||
如果你要查找的是 **活跃 Memory** 的功能开关和子智能体配置，它位于 `plugins.entries.active-memory` 下，而不是 `memorySearch`。
|
||||
如果你要查找 **active memory** 功能开关和子智能体配置，它位于 `plugins.entries.active-memory` 下，而不是 `memorySearch`。
|
||||
|
||||
活跃 Memory 使用双门控模型：
|
||||
Active memory 使用双门控模型：
|
||||
|
||||
1. 必须启用该插件，并且其目标为当前智能体 id
|
||||
1. 必须启用该插件，并且目标是当前智能体 id
|
||||
2. 该请求必须是符合条件的交互式持久聊天会话
|
||||
|
||||
有关激活模型、插件自有配置、对话记录持久化和安全上线模式，请参见 [Active Memory](/zh-CN/concepts/active-memory)。
|
||||
有关激活模型、插件自有配置、转录持久化和安全上线模式，请参阅 [Active Memory](/zh-CN/concepts/active-memory)。
|
||||
</Note>
|
||||
|
||||
---
|
||||
|
||||
## 提供商选择
|
||||
|
||||
| 键 | 类型 | 默认值 | 描述 |
|
||||
| ---------- | --------- | -------------- | ----------------------------------------------------------------------------------------------------------- |
|
||||
| 键 | 类型 | 默认值 | 说明 |
|
||||
| ---------- | --------- | -------------- | ------------------------------------------------------------------------------------------------------------- |
|
||||
| `provider` | `string` | 自动检测 | 嵌入适配器 ID：`bedrock`、`gemini`、`github-copilot`、`local`、`mistral`、`ollama`、`openai`、`voyage` |
|
||||
| `model` | `string` | 提供商默认值 | 嵌入模型名称 |
|
||||
| `fallback` | `string` | `"none"` | 当主提供商失败时使用的回退适配器 ID |
|
||||
| `enabled` | `boolean` | `true` | 启用或禁用 Memory 搜索 |
|
||||
| `model` | `string` | 提供商默认值 | 嵌入模型名称 |
|
||||
| `fallback` | `string` | `"none"` | 当主提供商失败时使用的回退适配器 ID |
|
||||
| `enabled` | `boolean` | `true` | 启用或禁用 Memory 搜索 |
|
||||
|
||||
### 自动检测顺序
|
||||
|
||||
@ -66,53 +66,53 @@ x-i18n:
|
||||
|
||||
<Steps>
|
||||
<Step title="local">
|
||||
如果已配置 `memorySearch.local.modelPath` 且该文件存在，则会选中。
|
||||
如果已配置 `memorySearch.local.modelPath` 且该文件存在，则选中。
|
||||
</Step>
|
||||
<Step title="github-copilot">
|
||||
如果可以解析到 GitHub Copilot token（环境变量或认证配置文件），则会选中。
|
||||
如果可以解析到 GitHub Copilot token（环境变量或 auth profile），则选中。
|
||||
</Step>
|
||||
<Step title="openai">
|
||||
如果可以解析到 OpenAI 密钥，则会选中。
|
||||
如果可以解析到 OpenAI 密钥，则选中。
|
||||
</Step>
|
||||
<Step title="gemini">
|
||||
如果可以解析到 Gemini 密钥，则会选中。
|
||||
如果可以解析到 Gemini 密钥，则选中。
|
||||
</Step>
|
||||
<Step title="voyage">
|
||||
如果可以解析到 Voyage 密钥，则会选中。
|
||||
如果可以解析到 Voyage 密钥，则选中。
|
||||
</Step>
|
||||
<Step title="mistral">
|
||||
如果可以解析到 Mistral 密钥，则会选中。
|
||||
如果可以解析到 Mistral 密钥，则选中。
|
||||
</Step>
|
||||
<Step title="bedrock">
|
||||
如果 AWS SDK 凭证链可解析（实例角色、访问密钥、profile、SSO、web identity 或共享配置），则会选中。
|
||||
如果 AWS SDK 凭证链可以解析成功（实例角色、访问密钥、profile、SSO、web identity 或共享配置），则选中。
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
支持 `ollama`，但不会自动检测（请显式设置）。
|
||||
支持 `ollama`，但不会自动检测到它（请显式设置）。
|
||||
|
||||
### API 密钥解析
|
||||
|
||||
远程嵌入需要 API 密钥。Bedrock 则改用 AWS SDK 默认凭证链（实例角色、SSO、访问密钥）。
|
||||
远程嵌入需要 API 密钥。Bedrock 则改为使用 AWS SDK 默认凭证链（实例角色、SSO、访问密钥）。
|
||||
|
||||
| 提供商 | 环境变量 | 配置键 |
|
||||
| -------------- | -------------------------------------------------- | --------------------------------- |
|
||||
| Bedrock | AWS 凭证链 | 不需要 API 密钥 |
|
||||
| Gemini | `GEMINI_API_KEY` | `models.providers.google.apiKey` |
|
||||
| GitHub Copilot | `COPILOT_GITHUB_TOKEN`, `GH_TOKEN`, `GITHUB_TOKEN` | 通过设备登录的认证配置文件 |
|
||||
| Mistral | `MISTRAL_API_KEY` | `models.providers.mistral.apiKey` |
|
||||
| Ollama | `OLLAMA_API_KEY`（占位符） | -- |
|
||||
| OpenAI | `OPENAI_API_KEY` | `models.providers.openai.apiKey` |
|
||||
| Voyage | `VOYAGE_API_KEY` | `models.providers.voyage.apiKey` |
|
||||
| 提供商 | 环境变量 | 配置键 |
|
||||
| --------------- | -------------------------------------------------- | --------------------------------- |
|
||||
| Bedrock | AWS 凭证链 | 不需要 API 密钥 |
|
||||
| Gemini | `GEMINI_API_KEY` | `models.providers.google.apiKey` |
|
||||
| GitHub Copilot | `COPILOT_GITHUB_TOKEN`、`GH_TOKEN`、`GITHUB_TOKEN` | 通过设备登录的 auth profile |
|
||||
| Mistral | `MISTRAL_API_KEY` | `models.providers.mistral.apiKey` |
|
||||
| Ollama | `OLLAMA_API_KEY`（占位符） | -- |
|
||||
| OpenAI | `OPENAI_API_KEY` | `models.providers.openai.apiKey` |
|
||||
| Voyage | `VOYAGE_API_KEY` | `models.providers.voyage.apiKey` |
|
||||
|
||||
<Note>
|
||||
Codex OAuth 仅覆盖 chat/completions，不满足嵌入请求的要求。
|
||||
Codex OAuth 仅覆盖 chat/completions，不满足嵌入请求。
|
||||
</Note>
|
||||
|
||||
---
|
||||
|
||||
## 远程端点配置
|
||||
|
||||
用于自定义兼容 OpenAI 的端点，或覆盖提供商默认值：
|
||||
用于自定义兼容 OpenAI 的端点或覆盖提供商默认值：
|
||||
|
||||
<ParamField path="remote.baseUrl" type="string">
|
||||
自定义 API 基础 URL。
|
||||
@ -121,7 +121,7 @@ Codex OAuth 仅覆盖 chat/completions，不满足嵌入请求的要求。
|
||||
覆盖 API 密钥。
|
||||
</ParamField>
|
||||
<ParamField path="remote.headers" type="object">
|
||||
额外的 HTTP 标头（会与提供商默认值合并）。
|
||||
额外的 HTTP 标头（与提供商默认值合并）。
|
||||
</ParamField>
|
||||
|
||||
```json5
|
||||
@ -147,24 +147,24 @@ Codex OAuth 仅覆盖 chat/completions，不满足嵌入请求的要求。
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Gemini">
|
||||
| 键 | 类型 | 默认值 | 描述 |
|
||||
| 键 | 类型 | 默认值 | 说明 |
|
||||
| ---------------------- | -------- | ---------------------- | ------------------------------------------ |
|
||||
| `model` | `string` | `gemini-embedding-001` | 也支持 `gemini-embedding-2-preview` |
|
||||
| `outputDimensionality` | `number` | `3072` | 对于 Embedding 2：768、1536 或 3072 |
|
||||
|
||||
<Warning>
|
||||
更改模型或 `outputDimensionality` 会触发自动全量重新索引。
|
||||
更改模型或 `outputDimensionality` 会触发自动的完整重新索引。
|
||||
</Warning>
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="OpenAI-compatible 输入类型">
|
||||
兼容 OpenAI 的嵌入端点可以选择启用提供商特定的 `input_type` 请求字段。这对于需要为查询嵌入和文档嵌入使用不同标签的非对称嵌入模型非常有用。
|
||||
<Accordion title="兼容 OpenAI 的输入类型">
|
||||
兼容 OpenAI 的嵌入端点可以选择启用提供商专用的 `input_type` 请求字段。这对于需要为查询嵌入和文档嵌入使用不同标签的非对称嵌入模型很有用。
|
||||
|
||||
| 键 | 类型 | 默认值 | 描述 |
|
||||
| ------------------- | -------- | ------ | ------------------------------------------------- |
|
||||
| `inputType` | `string` | 未设置 | 查询嵌入和文档嵌入共用的 `input_type` |
|
||||
| `queryInputType` | `string` | 未设置 | 查询时的 `input_type`；覆盖 `inputType` |
|
||||
| `documentInputType` | `string` | 未设置 | 索引/文档的 `input_type`；覆盖 `inputType` |
|
||||
| 键 | 类型 | 默认值 | 说明 |
|
||||
| ------------------- | -------- | ------ | --------------------------------------------------- |
|
||||
| `inputType` | `string` | 未设置 | 查询嵌入和文档嵌入共享的 `input_type` |
|
||||
| `queryInputType` | `string` | 未设置 | 查询时的 `input_type`；覆盖 `inputType` |
|
||||
| `documentInputType` | `string` | 未设置 | 索引/文档的 `input_type`；覆盖 `inputType` |
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -185,11 +185,11 @@ Codex OAuth 仅覆盖 chat/completions，不满足嵌入请求的要求。
|
||||
}
|
||||
```
|
||||
|
||||
更改这些值会影响提供商批量索引的嵌入缓存标识；如果上游模型对这些标签区别对待，则应随后执行一次 Memory 重新索引。
|
||||
更改这些值会影响提供商批量索引的嵌入缓存标识；当上游模型对这些标签有不同处理时，应随后执行一次 Memory 重新索引。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Bedrock">
|
||||
Bedrock 使用 AWS SDK 默认凭证链——不需要 API 密钥。如果 OpenClaw 在带有 Bedrock 权限实例角色的 EC2 上运行，只需设置提供商和模型：
|
||||
Bedrock 使用 AWS SDK 默认凭证链——不需要 API 密钥。如果 OpenClaw 运行在带有 Bedrock 权限实例角色的 EC2 上，只需设置提供商和模型：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -204,29 +204,29 @@ Codex OAuth 仅覆盖 chat/completions，不满足嵌入请求的要求。
|
||||
}
|
||||
```
|
||||
|
||||
| 键 | 类型 | 默认值 | 描述 |
|
||||
| ---------------------- | -------- | ------------------------------ | ----------------------------- |
|
||||
| `model` | `string` | `amazon.titan-embed-text-v2:0` | 任意 Bedrock 嵌入模型 ID |
|
||||
| 键 | 类型 | 默认值 | 说明 |
|
||||
| ---------------------- | -------- | ------------------------------ | ---------------------------- |
|
||||
| `model` | `string` | `amazon.titan-embed-text-v2:0` | 任意 Bedrock 嵌入模型 ID |
|
||||
| `outputDimensionality` | `number` | 模型默认值 | 对于 Titan V2：256、512 或 1024 |
|
||||
|
||||
**支持的模型**（包含家族检测和默认维度）：
|
||||
**支持的模型**（含系列检测和维度默认值）：
|
||||
|
||||
| 模型 ID | 提供商 | 默认维度 | 可配置维度 |
|
||||
| ------------------------------------------ | ---------- | -------- | ------------------- |
|
||||
| `amazon.titan-embed-text-v2:0` | Amazon | 1024 | 256、512、1024 |
|
||||
| `amazon.titan-embed-text-v1` | Amazon | 1536 | -- |
|
||||
| `amazon.titan-embed-g1-text-02` | Amazon | 1536 | -- |
|
||||
| `amazon.titan-embed-image-v1` | Amazon | 1024 | -- |
|
||||
| `amazon.nova-2-multimodal-embeddings-v1:0` | Amazon | 1024 | 256、384、1024、3072 |
|
||||
| `cohere.embed-english-v3` | Cohere | 1024 | -- |
|
||||
| `cohere.embed-multilingual-v3` | Cohere | 1024 | -- |
|
||||
| `cohere.embed-v4:0` | Cohere | 1536 | 256-1536 |
|
||||
| `twelvelabs.marengo-embed-3-0-v1:0` | TwelveLabs | 512 | -- |
|
||||
| `twelvelabs.marengo-embed-2-7-v1:0` | TwelveLabs | 1024 | -- |
|
||||
| 模型 ID | 提供商 | 默认维度 | 可配置维度 |
|
||||
| ------------------------------------------ | ----------- | -------- | -------------------- |
|
||||
| `amazon.titan-embed-text-v2:0` | Amazon | 1024 | 256、512、1024 |
|
||||
| `amazon.titan-embed-text-v1` | Amazon | 1536 | -- |
|
||||
| `amazon.titan-embed-g1-text-02` | Amazon | 1536 | -- |
|
||||
| `amazon.titan-embed-image-v1` | Amazon | 1024 | -- |
|
||||
| `amazon.nova-2-multimodal-embeddings-v1:0` | Amazon | 1024 | 256、384、1024、3072 |
|
||||
| `cohere.embed-english-v3` | Cohere | 1024 | -- |
|
||||
| `cohere.embed-multilingual-v3` | Cohere | 1024 | -- |
|
||||
| `cohere.embed-v4:0` | Cohere | 1536 | 256-1536 |
|
||||
| `twelvelabs.marengo-embed-3-0-v1:0` | TwelveLabs | 512 | -- |
|
||||
| `twelvelabs.marengo-embed-2-7-v1:0` | TwelveLabs | 1024 | -- |
|
||||
|
||||
带吞吐量后缀的变体（例如 `amazon.titan-embed-text-v1:2:8k`）会继承基础模型的配置。
|
||||
|
||||
**认证：** Bedrock 认证使用标准 AWS SDK 凭证解析顺序：
|
||||
**认证：**Bedrock 认证使用标准 AWS SDK 凭证解析顺序：
|
||||
|
||||
1. 环境变量（`AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY`）
|
||||
2. SSO token 缓存
|
||||
@ -234,9 +234,9 @@ Codex OAuth 仅覆盖 chat/completions，不满足嵌入请求的要求。
|
||||
4. 共享凭证和配置文件
|
||||
5. ECS 或 EC2 元数据凭证
|
||||
|
||||
区域会从 `AWS_REGION`、`AWS_DEFAULT_REGION`、`amazon-bedrock` 提供商的 `baseUrl` 中解析，或默认使用 `us-east-1`。
|
||||
区域从 `AWS_REGION`、`AWS_DEFAULT_REGION`、`amazon-bedrock` 提供商的 `baseUrl` 中解析，或默认使用 `us-east-1`。
|
||||
|
||||
**IAM 权限：** IAM 角色或用户需要：
|
||||
**IAM 权限：**IAM 角色或用户需要：
|
||||
|
||||
```json
|
||||
{
|
||||
@ -246,30 +246,30 @@ Codex OAuth 仅覆盖 chat/completions，不满足嵌入请求的要求。
|
||||
}
|
||||
```
|
||||
|
||||
为了实现最小权限原则，请将 `InvokeModel` 限定到特定模型：
|
||||
为实现最小权限原则，请将 `InvokeModel` 限定到具体模型：
|
||||
|
||||
```
|
||||
arn:aws:bedrock:*::foundation-model/amazon.titan-embed-text-v2:0
|
||||
```
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Local（GGUF + node-llama-cpp）">
|
||||
| 键 | 类型 | 默认值 | 描述 |
|
||||
| --------------------- | ------------------ | ---------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `local.modelPath` | `string` | 自动下载 | GGUF 模型文件的路径 |
|
||||
| `local.modelCacheDir` | `string` | node-llama-cpp 默认值 | 已下载模型的缓存目录 |
|
||||
| `local.contextSize` | `number \| "auto"` | `4096` | 嵌入上下文的上下文窗口大小。4096 可覆盖典型分块（128–512 token），同时限制非权重 VRAM 占用。在受限主机上可降到 1024–2048。`"auto"` 使用模型训练时的最大值——不建议用于 8B+ 模型（Qwen3-Embedding-8B：40 960 token → 约 32 GB VRAM，而在 4096 时约为 8.8 GB）。 |
|
||||
<Accordion title="本地（GGUF + node-llama-cpp）">
|
||||
| 键 | 类型 | 默认值 | 说明 |
|
||||
| --------------------- | ------------------ | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
||||
| `local.modelPath` | `string` | 自动下载 | GGUF 模型文件的路径 |
|
||||
| `local.modelCacheDir` | `string` | node-llama-cpp 默认值 | 已下载模型的缓存目录 |
|
||||
| `local.contextSize` | `number \| "auto"` | `4096` | 嵌入上下文的上下文窗口大小。4096 可覆盖典型分块（128–512 token），同时限制非权重 VRAM 占用。在资源受限的主机上可降至 1024–2048。`"auto"` 使用模型训练时的最大值——不建议用于 8B+ 模型（Qwen3-Embedding-8B：40 960 token → 约 32 GB VRAM，而 4096 时约为 8.8 GB）。 |
|
||||
|
||||
默认模型：`embeddinggemma-300m-qat-Q8_0.gguf`（约 0.6 GB，自动下载）。需要原生构建：`pnpm approve-builds`，然后执行 `pnpm rebuild node-llama-cpp`。
|
||||
|
||||
使用独立 CLI 验证 Gateway 网关所使用的相同提供商路径：
|
||||
使用独立 CLI 验证 Gateway 网关所使用的同一提供商路径：
|
||||
|
||||
```bash
|
||||
openclaw memory status --deep --agent main
|
||||
openclaw memory index --force --agent main
|
||||
```
|
||||
|
||||
如果 `provider` 为 `auto`，只有当 `local.modelPath` 指向现有本地文件时，才会选择 `local`。`hf:` 和 HTTP(S) 模型引用仍可在显式设置 `provider: "local"` 时使用，但在模型尚未落盘前，它们不会让 `auto` 优先选择 local。
|
||||
如果 `provider` 为 `auto`，只有当 `local.modelPath` 指向现有本地文件时，才会选择 `local`。`hf:` 和 HTTP(S) 模型引用仍然可以在 `provider: "local"` 时显式使用，但在模型尚未落盘可用之前，它们不会让 `auto` 优先选择 local。
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@ -279,7 +279,7 @@ Codex OAuth 仅覆盖 chat/completions，不满足嵌入请求的要求。
|
||||
<ParamField path="sync.embeddingBatchTimeoutSeconds" type="number">
|
||||
覆盖 Memory 索引期间内联嵌入批次的超时时间。
|
||||
|
||||
未设置时使用提供商默认值：对于 `local`、`ollama` 和 `lmstudio` 等本地/自托管提供商为 600 秒，对于托管提供商为 120 秒。当本地 CPU 密集型嵌入批次运行正常但较慢时，可增大此值。
|
||||
未设置时使用提供商默认值：对于 `local`、`ollama` 和 `lmstudio` 等本地/自托管提供商为 600 秒，对于托管提供商为 120 秒。当本地 CPU 密集型嵌入批次运行正常但速度较慢时，可增大此值。
|
||||
</ParamField>
|
||||
|
||||
---
|
||||
@ -288,27 +288,27 @@ Codex OAuth 仅覆盖 chat/completions，不满足嵌入请求的要求。
|
||||
|
||||
全部位于 `memorySearch.query.hybrid` 下：
|
||||
|
||||
| 键 | 类型 | 默认值 | 描述 |
|
||||
| 键 | 类型 | 默认值 | 说明 |
|
||||
| --------------------- | --------- | ------ | ---------------------------- |
|
||||
| `enabled` | `boolean` | `true` | 启用混合 BM25 + 向量搜索 |
|
||||
| `enabled` | `boolean` | `true` | 启用 BM25 + 向量混合搜索 |
|
||||
| `vectorWeight` | `number` | `0.7` | 向量分数的权重（0-1） |
|
||||
| `textWeight` | `number` | `0.3` | BM25 分数的权重（0-1） |
|
||||
| `candidateMultiplier` | `number` | `4` | 候选池大小乘数 |
|
||||
|
||||
<Tabs>
|
||||
<Tab title="MMR（多样性）">
|
||||
| 键 | 类型 | 默认值 | 描述 |
|
||||
| ------------- | --------- | ------- | ---------------------------------- |
|
||||
| `mmr.enabled` | `boolean` | `false` | 启用 MMR 重排序 |
|
||||
| `mmr.lambda` | `number` | `0.7` | 0 = 最大多样性，1 = 最大相关性 |
|
||||
| 键 | 类型 | 默认值 | 说明 |
|
||||
| ------------- | --------- | ------ | -------------------------------- |
|
||||
| `mmr.enabled` | `boolean` | `false` | 启用 MMR 重排序 |
|
||||
| `mmr.lambda` | `number` | `0.7` | 0 = 最大多样性，1 = 最大相关性 |
|
||||
</Tab>
|
||||
<Tab title="时间衰减（新近性）">
|
||||
| 键 | 类型 | 默认值 | 描述 |
|
||||
| ---------------------------- | --------- | ------- | ----------------------- |
|
||||
| `temporalDecay.enabled` | `boolean` | `false` | 启用新近性加权 |
|
||||
| `temporalDecay.halfLifeDays` | `number` | `30` | 分数每 N 天减半 |
|
||||
<Tab title="时间衰减（时效性）">
|
||||
| 键 | 类型 | 默认值 | 说明 |
|
||||
| ---------------------------- | --------- | ------ | ----------------------- |
|
||||
| `temporalDecay.enabled` | `boolean` | `false` | 启用时效性加权 |
|
||||
| `temporalDecay.halfLifeDays` | `number` | `30` | 分数每 N 天减半 |
|
||||
|
||||
常青文件（`MEMORY.md`、`memory/` 中不带日期的文件）永远不会衰减。
|
||||
常青文件（`MEMORY.md`、`memory/` 中无日期的文件）永不衰减。
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
@ -338,9 +338,9 @@ Codex OAuth 仅覆盖 chat/completions，不满足嵌入请求的要求。
|
||||
|
||||
## 额外 Memory 路径
|
||||
|
||||
| 键 | 类型 | 描述 |
|
||||
| 键 | 类型 | 说明 |
|
||||
| ------------ | ---------- | ------------------------------ |
|
||||
| `extraPaths` | `string[]` | 要建立索引的额外目录或文件 |
|
||||
| `extraPaths` | `string[]` | 要索引的其他目录或文件 |
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -354,80 +354,80 @@ Codex OAuth 仅覆盖 chat/completions，不满足嵌入请求的要求。
|
||||
}
|
||||
```
|
||||
|
||||
路径可以是绝对路径，也可以是相对于工作区的路径。目录会递归扫描 `.md` 文件。符号链接的处理方式取决于当前后端：内置引擎会忽略符号链接，而 QMD 会遵循底层 QMD 扫描器的行为。
|
||||
路径可以是绝对路径或相对于工作区的路径。目录会递归扫描其中的 `.md` 文件。符号链接的处理取决于当前后端：内置引擎会忽略符号链接，而 QMD 会遵循底层 QMD 扫描器的行为。
|
||||
|
||||
对于按智能体范围进行的跨智能体对话记录搜索，请使用 `agents.list[].memorySearch.qmd.extraCollections`，而不是 `memory.qmd.paths`。这些额外集合遵循相同的 `{ path, name, pattern? }` 结构，但会按智能体合并，并且当路径指向当前工作区之外时，可以保留显式共享名称。如果同一个解析后路径同时出现在 `memory.qmd.paths` 和 `memorySearch.qmd.extraCollections` 中，QMD 会保留第一项并跳过重复项。
|
||||
对于按智能体范围的跨智能体转录搜索，请使用 `agents.list[].memorySearch.qmd.extraCollections`，而不是 `memory.qmd.paths`。这些额外集合沿用相同的 `{ path, name, pattern? }` 结构，但会按每个智能体合并，并且当路径指向当前工作区之外时，可以保留显式共享名称。如果同一解析后路径同时出现在 `memory.qmd.paths` 和 `memorySearch.qmd.extraCollections` 中，QMD 会保留第一项并跳过重复项。
|
||||
|
||||
---
|
||||
|
||||
## 多模态 Memory（Gemini）
|
||||
|
||||
使用 Gemini Embedding 2，为图片和音频与 Markdown 一起建立索引：
|
||||
使用 Gemini Embedding 2 在 Markdown 之外同时索引图像和音频：
|
||||
|
||||
| 键 | 类型 | 默认值 | 描述 |
|
||||
| ------------------------- | ---------- | ---------- | ------------------------------------ |
|
||||
| `multimodal.enabled` | `boolean` | `false` | 启用多模态索引 |
|
||||
| 键 | 类型 | 默认值 | 说明 |
|
||||
| ------------------------- | ---------- | ---------- | ----------------------------------- |
|
||||
| `multimodal.enabled` | `boolean` | `false` | 启用多模态索引 |
|
||||
| `multimodal.modalities` | `string[]` | -- | `["image"]`、`["audio"]` 或 `["all"]` |
|
||||
| `multimodal.maxFileBytes` | `number` | `10000000` | 建立索引的最大文件大小 |
|
||||
| `multimodal.maxFileBytes` | `number` | `10000000` | 可索引文件的最大大小 |
|
||||
|
||||
<Note>
|
||||
仅适用于 `extraPaths` 中的文件。默认 Memory 根目录仍然只支持 Markdown。需要 `gemini-embedding-2-preview`。`fallback` 必须为 `"none"`。
|
||||
仅适用于 `extraPaths` 中的文件。默认 Memory 根目录仍仅支持 Markdown。需要 `gemini-embedding-2-preview`。`fallback` 必须为 `"none"`。
|
||||
</Note>
|
||||
|
||||
支持的格式：`.jpg`、`.jpeg`、`.png`、`.webp`、`.gif`、`.heic`、`.heif`（图片）；`.mp3`、`.wav`、`.ogg`、`.opus`、`.m4a`、`.aac`、`.flac`（音频）。
|
||||
支持的格式：`.jpg`、`.jpeg`、`.png`、`.webp`、`.gif`、`.heic`、`.heif`（图像）；`.mp3`、`.wav`、`.ogg`、`.opus`、`.m4a`、`.aac`、`.flac`（音频）。
|
||||
|
||||
---
|
||||
|
||||
## 嵌入缓存
|
||||
|
||||
| 键 | 类型 | 默认值 | 描述 |
|
||||
| ------------------ | --------- | ------- | ------------------------------- |
|
||||
| `cache.enabled` | `boolean` | `false` | 在 SQLite 中缓存分块嵌入 |
|
||||
| `cache.maxEntries` | `number` | `50000` | 最大缓存嵌入数量 |
|
||||
| 键 | 类型 | 默认值 | 说明 |
|
||||
| ------------------ | --------- | ------- | ------------------------------ |
|
||||
| `cache.enabled` | `boolean` | `false` | 在 SQLite 中缓存分块嵌入 |
|
||||
| `cache.maxEntries` | `number` | `50000` | 最大缓存嵌入条目数 |
|
||||
|
||||
可防止在重新索引或更新对话记录时，对未更改的文本重复生成嵌入。
|
||||
可防止在重新索引或转录更新期间对未变更文本重复生成嵌入。
|
||||
|
||||
---
|
||||
|
||||
## 批量索引
|
||||
|
||||
| 键 | 类型 | 默认值 | 描述 |
|
||||
| ----------------------------- | --------- | ------- | -------------------- |
|
||||
| `remote.batch.enabled` | `boolean` | `false` | 启用批量嵌入 API |
|
||||
| `remote.batch.concurrency` | `number` | `2` | 并行批处理任务数 |
|
||||
| `remote.batch.wait` | `boolean` | `true` | 等待批处理完成 |
|
||||
| `remote.batch.pollIntervalMs` | `number` | -- | 轮询间隔 |
|
||||
| `remote.batch.timeoutMinutes` | `number` | -- | 批处理超时时间 |
|
||||
| 键 | 类型 | 默认值 | 说明 |
|
||||
| ----------------------------- | --------- | ------- | ------------------------ |
|
||||
| `remote.batch.enabled` | `boolean` | `false` | 启用批量嵌入 API |
|
||||
| `remote.batch.concurrency` | `number` | `2` | 并行批处理作业数 |
|
||||
| `remote.batch.wait` | `boolean` | `true` | 等待批处理完成 |
|
||||
| `remote.batch.pollIntervalMs` | `number` | -- | 轮询间隔 |
|
||||
| `remote.batch.timeoutMinutes` | `number` | -- | 批处理超时时间 |
|
||||
|
||||
适用于 `openai`、`gemini` 和 `voyage`。对于大规模回填，OpenAI 批处理通常最快且成本最低。
|
||||
适用于 `openai`、`gemini` 和 `voyage`。对于大规模回填，OpenAI 批处理通常最快且最便宜。
|
||||
|
||||
这与 `sync.embeddingBatchTimeoutSeconds` 是分开的；后者用于控制内联嵌入调用，适用于本地/自托管提供商，以及在未启用提供商批量 API 时的托管提供商。
|
||||
这与 `sync.embeddingBatchTimeoutSeconds` 是分开的；后者控制内联嵌入调用，供本地/自托管提供商使用，以及在未启用提供商批量 API 时供托管提供商使用。
|
||||
|
||||
---
|
||||
|
||||
## 会话 Memory 搜索（实验性）
|
||||
|
||||
为会话对话记录建立索引，并通过 `memory_search` 提供结果：
|
||||
对会话转录建立索引，并通过 `memory_search` 提供结果：
|
||||
|
||||
| 键 | 类型 | 默认值 | 描述 |
|
||||
| 键 | 类型 | 默认值 | 说明 |
|
||||
| ----------------------------- | ---------- | ------------ | ------------------------------------- |
|
||||
| `experimental.sessionMemory` | `boolean` | `false` | 启用会话索引 |
|
||||
| `sources` | `string[]` | `["memory"]` | 添加 `"sessions"` 以包含对话记录 |
|
||||
| `sources` | `string[]` | `["memory"]` | 添加 `"sessions"` 以包含转录 |
|
||||
| `sync.sessions.deltaBytes` | `number` | `100000` | 触发重新索引的字节阈值 |
|
||||
| `sync.sessions.deltaMessages` | `number` | `50` | 触发重新索引的消息阈值 |
|
||||
|
||||
<Warning>
|
||||
会话索引需要显式启用，并且以异步方式运行。结果可能会有轻微滞后。会话日志存储在磁盘上，因此应将文件系统访问视为信任边界。
|
||||
会话索引需要显式启用，并且异步运行。结果可能会有轻微延迟。会话日志存储在磁盘上，因此请将文件系统访问视为信任边界。
|
||||
</Warning>
|
||||
|
||||
---
|
||||
|
||||
## SQLite 向量加速（sqlite-vec）
|
||||
|
||||
| 键 | 类型 | 默认值 | 描述 |
|
||||
| ---------------------------- | --------- | ------- | --------------------------------- |
|
||||
| `store.vector.enabled` | `boolean` | `true` | 对向量查询使用 sqlite-vec |
|
||||
| `store.vector.extensionPath` | `string` | 内置 | 覆盖 sqlite-vec 路径 |
|
||||
| 键 | 类型 | 默认值 | 说明 |
|
||||
| ---------------------------- | --------- | -------- | --------------------------------- |
|
||||
| `store.vector.enabled` | `boolean` | `true` | 使用 sqlite-vec 执行向量查询 |
|
||||
| `store.vector.extensionPath` | `string` | 内置 | 覆盖 sqlite-vec 路径 |
|
||||
|
||||
当 sqlite-vec 不可用时，OpenClaw 会自动回退到进程内余弦相似度计算。
|
||||
|
||||
@ -435,10 +435,10 @@ Codex OAuth 仅覆盖 chat/completions，不满足嵌入请求的要求。
|
||||
|
||||
## 索引存储
|
||||
|
||||
| 键 | 类型 | 默认值 | 描述 |
|
||||
| --------------------- | -------- | ------------------------------------- | ---------------------------------------- |
|
||||
| `store.path` | `string` | `~/.openclaw/memory/{agentId}.sqlite` | 索引位置（支持 `{agentId}` token） |
|
||||
| `store.fts.tokenizer` | `string` | `unicode61` | FTS5 分词器（`unicode61` 或 `trigram`） |
|
||||
| 键 | 类型 | 默认值 | 说明 |
|
||||
| --------------------- | -------- | ------------------------------------- | ------------------------------------- |
|
||||
| `store.path` | `string` | `~/.openclaw/memory/{agentId}.sqlite` | 索引位置（支持 `{agentId}` token） |
|
||||
| `store.fts.tokenizer` | `string` | `unicode61` | FTS5 分词器（`unicode61` 或 `trigram`） |
|
||||
|
||||
---
|
||||
|
||||
@ -446,47 +446,47 @@ Codex OAuth 仅覆盖 chat/completions，不满足嵌入请求的要求。
|
||||
|
||||
设置 `memory.backend = "qmd"` 以启用。所有 QMD 设置都位于 `memory.qmd` 下：
|
||||
|
||||
| 键 | 类型 | 默认值 | 描述 |
|
||||
| 键 | 类型 | 默认值 | 说明 |
|
||||
| ------------------------ | --------- | -------- | -------------------------------------------- |
|
||||
| `command` | `string` | `qmd` | QMD 可执行文件路径 |
|
||||
| `searchMode` | `string` | `search` | 搜索命令：`search`、`vsearch`、`query` |
|
||||
| `includeDefaultMemory` | `boolean` | `true` | 自动索引 `MEMORY.md` + `memory/**/*.md` |
|
||||
| `paths[]` | `array` | -- | 额外路径：`{ name, path, pattern? }` |
|
||||
| `sessions.enabled` | `boolean` | `false` | 为会话对话记录建立索引 |
|
||||
| `sessions.retentionDays` | `number` | -- | 对话记录保留期 |
|
||||
| `sessions.enabled` | `boolean` | `false` | 索引会话转录 |
|
||||
| `sessions.retentionDays` | `number` | -- | 转录保留期 |
|
||||
| `sessions.exportDir` | `string` | -- | 导出目录 |
|
||||
|
||||
`searchMode: "search"` 仅支持词法/BM25 搜索。OpenClaw 不会为该模式运行语义向量就绪性探测或 QMD 嵌入维护，包括在 `memory status --deep` 期间；`vsearch` 和 `query` 则仍然需要 QMD 向量就绪性和嵌入。
|
||||
`searchMode: "search"` 仅为词法/BM25 搜索。OpenClaw 不会为该模式运行语义向量就绪性探测或 QMD 嵌入维护，包括在执行 `memory status --deep` 期间；`vsearch` 和 `query` 仍然要求 QMD 向量已就绪且嵌入可用。
|
||||
|
||||
OpenClaw 优先使用当前的 QMD collection 和 MCP 查询结构，但也会通过回退到旧版 `--mask` collection 标志和旧版 MCP 工具名称来保持与较早 QMD 版本的兼容。
|
||||
OpenClaw 优先使用当前的 QMD collection 和 MCP 查询格式，但也会在需要时尝试兼容的 collection pattern 标志和较旧的 MCP 工具名称，以保持旧版 QMD 仍可用。
|
||||
|
||||
<Note>
|
||||
QMD 模型覆盖保留在 QMD 侧，而不是 OpenClaw 配置中。如果你需要全局覆盖 QMD 的模型，请在 Gateway 网关运行时环境中设置环境变量，例如 `QMD_EMBED_MODEL`、`QMD_RERANK_MODEL` 和 `QMD_GENERATE_MODEL`。
|
||||
QMD 模型覆盖应保留在 QMD 侧，而不是放在 OpenClaw 配置中。如果你需要全局覆盖 QMD 的模型，请在 Gateway 网关运行时环境中设置环境变量，例如 `QMD_EMBED_MODEL`、`QMD_RERANK_MODEL` 和 `QMD_GENERATE_MODEL`。
|
||||
</Note>
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="更新计划">
|
||||
| 键 | 类型 | 默认值 | 描述 |
|
||||
| ------------------------- | --------- | ------- | ------------------------------ |
|
||||
| `update.interval` | `string` | `5m` | 刷新间隔 |
|
||||
| `update.debounceMs` | `number` | `15000` | 文件变更去抖动 |
|
||||
| `update.onBoot` | `boolean` | `true` | 启动时刷新 |
|
||||
| `update.waitForBootSync` | `boolean` | `false` | 在刷新完成前阻塞启动 |
|
||||
| `update.embedInterval` | `string` | -- | 单独的嵌入执行周期 |
|
||||
| `update.commandTimeoutMs` | `number` | -- | QMD 命令的超时时间 |
|
||||
| `update.updateTimeoutMs` | `number` | -- | QMD 更新操作的超时时间 |
|
||||
| `update.embedTimeoutMs` | `number` | -- | QMD 嵌入操作的超时时间 |
|
||||
| 键 | 类型 | 默认值 | 说明 |
|
||||
| ------------------------- | --------- | ------- | -------------------------------- |
|
||||
| `update.interval` | `string` | `5m` | 刷新间隔 |
|
||||
| `update.debounceMs` | `number` | `15000` | 文件变更防抖 |
|
||||
| `update.onBoot` | `boolean` | `true` | 启动时刷新 |
|
||||
| `update.waitForBootSync` | `boolean` | `false` | 在刷新完成前阻塞启动 |
|
||||
| `update.embedInterval` | `string` | -- | 单独的嵌入执行周期 |
|
||||
| `update.commandTimeoutMs` | `number` | -- | QMD 命令超时时间 |
|
||||
| `update.updateTimeoutMs` | `number` | -- | QMD 更新操作超时时间 |
|
||||
| `update.embedTimeoutMs` | `number` | -- | QMD 嵌入操作超时时间 |
|
||||
</Accordion>
|
||||
<Accordion title="限制">
|
||||
| 键 | 类型 | 默认值 | 描述 |
|
||||
| ------------------------- | -------- | ------- | ------------------------ |
|
||||
| `limits.maxResults` | `number` | `6` | 最大搜索结果数 |
|
||||
| `limits.maxSnippetChars` | `number` | -- | 限制摘要长度 |
|
||||
| `limits.maxInjectedChars` | `number` | -- | 限制注入的总字符数 |
|
||||
| `limits.timeoutMs` | `number` | `4000` | 搜索超时时间 |
|
||||
| 键 | 类型 | 默认值 | 说明 |
|
||||
| ------------------------- | -------- | ------- | -------------------------- |
|
||||
| `limits.maxResults` | `number` | `6` | 最大搜索结果数 |
|
||||
| `limits.maxSnippetChars` | `number` | -- | 限制摘要长度 |
|
||||
| `limits.maxInjectedChars` | `number` | -- | 限制注入的总字符数 |
|
||||
| `limits.timeoutMs` | `number` | `4000` | 搜索超时时间 |
|
||||
</Accordion>
|
||||
<Accordion title="范围">
|
||||
控制哪些会话可以接收 QMD 搜索结果。使用与 [`session.sendPolicy`](/zh-CN/gateway/config-agents#session) 相同的模式：
|
||||
控制哪些会话可以接收 QMD 搜索结果。其 schema 与 [`session.sendPolicy`](/zh-CN/gateway/config-agents#session) 相同：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -503,17 +503,17 @@ QMD 模型覆盖保留在 QMD 侧，而不是 OpenClaw 配置中。如果你需
|
||||
|
||||
已发布的默认配置允许 direct 和 channel 会话，同时仍然拒绝群组。
|
||||
|
||||
默认仅限私信。`match.keyPrefix` 匹配标准化后的会话键；`match.rawKeyPrefix` 匹配包含 `agent:<id>:` 的原始键。
|
||||
默认仅限私信。`match.keyPrefix` 匹配规范化后的会话键；`match.rawKeyPrefix` 匹配原始键，包括 `agent:<id>:`。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="引用">
|
||||
`memory.citations` 适用于所有后端：
|
||||
|
||||
| 值 | 行为 |
|
||||
| ---------------- | -------------------------------------------------- |
|
||||
| `auto`（默认） | 在摘要中包含 `Source: <path#line>` 页脚 |
|
||||
| `on` | 始终包含页脚 |
|
||||
| `off` | 省略页脚（路径仍会在内部传递给智能体） |
|
||||
| 值 | 行为 |
|
||||
| ---------------- | ------------------------------------------------- |
|
||||
| `auto`（默认） | 在摘要中包含 `Source: <path#line>` 页脚 |
|
||||
| `on` | 始终包含页脚 |
|
||||
| `off` | 省略页脚（路径仍会在内部传递给智能体） |
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@ -543,19 +543,19 @@ QMD 模型覆盖保留在 QMD 侧，而不是 OpenClaw 配置中。如果你需
|
||||
|
||||
## Dreaming
|
||||
|
||||
Dreaming 的配置位于 `plugins.entries.memory-core.config.dreaming` 下，而不是 `agents.defaults.memorySearch` 下。
|
||||
Dreaming 配置位于 `plugins.entries.memory-core.config.dreaming` 下，而不是 `agents.defaults.memorySearch` 下。
|
||||
|
||||
Dreaming 作为一次计划中的完整扫描运行，并将内部的 light/deep/REM 阶段作为实现细节使用。
|
||||
Dreaming 作为一次计划任务扫描运行，并将内部的 light/deep/REM 阶段作为实现细节使用。
|
||||
|
||||
有关概念性行为和斜杠命令，请参见 [Dreaming](/zh-CN/concepts/dreaming)。
|
||||
有关概念行为和斜杠命令，请参阅 [Dreaming](/zh-CN/concepts/dreaming)。
|
||||
|
||||
### 用户设置
|
||||
|
||||
| 键 | 类型 | 默认值 | 描述 |
|
||||
| ----------- | --------- | ----------- | ---------------------------------------- |
|
||||
| `enabled` | `boolean` | `false` | 完全启用或禁用 Dreaming |
|
||||
| `frequency` | `string` | `0 3 * * *` | 可选的完整 Dreaming 扫描 cron 周期 |
|
||||
| `model` | `string` | 默认模型 | 可选的 Dream Diary 子智能体模型覆盖 |
|
||||
| 键 | 类型 | 默认值 | 说明 |
|
||||
| ----------- | --------- | ------------- | ----------------------------------------- |
|
||||
| `enabled` | `boolean` | `false` | 完全启用或禁用 Dreaming |
|
||||
| `frequency` | `string` | `0 3 * * *` | 完整 Dreaming 扫描的可选 cron 周期 |
|
||||
| `model` | `string` | 默认模型 | 可选的 Dream Diary 子智能体模型覆盖 |
|
||||
|
||||
### 示例
|
||||
|
||||
@ -582,8 +582,8 @@ Dreaming 作为一次计划中的完整扫描运行，并将内部的 light/deep
|
||||
```
|
||||
|
||||
<Note>
|
||||
- Dreaming 会将机器状态写入 `memory/.dreams/`。
|
||||
- Dreaming 会将人类可读的叙事输出写入 `DREAMS.md`（或现有的 `dreams.md`）。
|
||||
- Dreaming 将机器状态写入 `memory/.dreams/`。
|
||||
- Dreaming 将人类可读的叙事输出写入 `DREAMS.md`（或现有的 `dreams.md`）。
|
||||
- `dreaming.model` 使用现有的插件子智能体信任门控；启用它之前，请先设置 `plugins.entries.memory-core.subagent.allowModelOverride: true`。
|
||||
- light/deep/REM 阶段策略和阈值属于内部行为，不是面向用户的配置。
|
||||
</Note>
|
||||
|
||||
@ -1,136 +1,137 @@
|
||||
---
|
||||
read_when:
|
||||
- 调整思考、快速模式或详细模式的指令解析或默认值
|
||||
summary: '`/think`、`/fast`、`/verbose`、`/trace` 以及推理可见性的指令语法'
|
||||
summary: '`/think`、`/fast`、`/verbose`、`/trace` 的指令语法以及推理可见性'
|
||||
title: 思考级别
|
||||
x-i18n:
|
||||
generated_at: "2026-04-27T13:19:40Z"
|
||||
generated_at: "2026-04-27T13:32:07Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 7eaa5f397e1ecc327b8706f3fee8cd44e4986ddc23159e20e6d026911eb331e0
|
||||
source_hash: 0d79dc5a84bb2e695fafb6f2298aabf253126dc20d474bc64ca19a7fe6ac5454
|
||||
source_path: tools/thinking.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
## 它的作用
|
||||
|
||||
- 可在任何入站消息正文中使用内联指令：`/t <level>`、`/think:<level>` 或 `/thinking <level>`。
|
||||
- 任何入站消息体中的内联指令：`/t <level>`、`/think:<level>` 或 `/thinking <level>`。
|
||||
- 级别（别名）：`off | minimal | low | medium | high | xhigh | adaptive | max`
|
||||
- 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`。
|
||||
- high → “超强思考”（最大预算）
|
||||
- xhigh → “超强思考+”（GPT-5.2+ 和 Codex 模型，以及 Anthropic Claude Opus 4.7 effort）
|
||||
- adaptive → 提供商管理的自适应思考（Anthropic/Bedrock 上的 Claude 4.6、Anthropic Claude Opus 4.7，以及 Google Gemini 动态思考支持此模式）
|
||||
- max → 提供商最大推理（Anthropic Claude Opus 4.7；Ollama 会将其映射到其最高原生 `think` effort）
|
||||
- `x-high`、`x_high`、`extra-high`、`extra high` 和 `extra_high` 都会映射到 `xhigh`。
|
||||
- `highest` 会映射到 `high`。
|
||||
- 提供商说明：
|
||||
- 思考菜单和选择器由 provider 配置文件驱动。提供商插件会为所选模型声明精确的级别集合，包括如二元 `on` 这样的标签。
|
||||
- 仅当 provider/模型配置文件支持时，才会展示 `adaptive`、`xhigh` 和 `max`。如果输入了不受支持级别的类型化指令，将拒绝该指令，并返回该模型的有效选项。
|
||||
- 已存储但不受支持的旧级别会按 provider 配置文件的等级重新映射。`adaptive` 在非自适应模型上会回退为 `medium`，而 `xhigh` 和 `max` 会回退为所选模型支持的最高非 `off` 级别。
|
||||
- 思考菜单和选择器由提供商配置文件驱动。提供商插件会为所选模型声明精确支持的级别集合，包括像二元 `on` 这样的标签。
|
||||
- 只有支持这些级别的提供商 / 模型配置文件才会声明 `adaptive`、`xhigh` 和 `max`。如果输入的指令级别不受支持，则会拒绝，并返回该模型的有效选项。
|
||||
- 已存储但不受支持的旧级别会按提供商配置文件等级重新映射。`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`。
|
||||
- Anthropic Claude Opus 4.7 默认不使用自适应思考。除非你显式设置思考级别，否则它的 API effort 默认值仍由提供商决定。
|
||||
- Anthropic Claude Opus 4.7 会将 `/think xhigh` 映射为自适应思考加 `output_config.effort: "xhigh"`，因为 `/think` 是思考指令，而 `xhigh` 是 Opus 4.7 的 effort 设置。
|
||||
- Anthropic Claude Opus 4.7 还支持 `/think max`；它会映射到同一条由提供商控制的最大 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 会省略禁用推理的 payload，而不是发送不受支持的值。
|
||||
- 过时的已配置 OpenRouter Hunter Alpha 引用会跳过代理推理注入，因为该已退役路由可能会通过推理字段返回最终答案文本。
|
||||
- Google Gemini 会将 `/think adaptive` 映射到 Gemini 由提供商控制的动态思考。Gemini 3 请求会省略固定的 `thinkingLevel`，而 Gemini 2.5 请求会发送 `thinkingBudget: -1`；固定级别仍会映射到该模型家族最接近的 Gemini `thinkingLevel` 或 budget。
|
||||
- Anthropic 兼容流式路径上的 MiniMax（`minimax/*`）默认使用 `thinking: { type: "disabled" }`，除非你在模型参数或请求参数中显式设置思考。这可避免 MiniMax 的非原生 Anthropic 流格式泄露 `reasoning_content` 增量。
|
||||
- Z.AI（`zai/*`）只支持二元思考（`on`/`off`）。任何非 `off` 级别都会被视为 `on`（映射到 `low`）。
|
||||
- Moonshot（`moonshot/*`）会将 `/think off` 映射到 `thinking: { type: "disabled" }`，并将任何非 `off` 级别映射到 `thinking: { type: "enabled" }`。启用思考时，Moonshot 只接受 `tool_choice` 为 `auto|none`；OpenClaw 会将不兼容的值规范化为 `auto`。
|
||||
|
||||
## 解析顺序
|
||||
|
||||
1. 消息上的内联指令（仅对该条消息生效）。
|
||||
2. 会话覆盖值（通过发送仅包含指令的消息设置）。
|
||||
1. 消息中的内联指令（仅作用于该条消息）。
|
||||
2. 会话覆盖（通过发送仅包含指令的消息来设置）。
|
||||
3. 每个智能体的默认值（配置中的 `agents.list[].thinkingDefault`）。
|
||||
4. 全局默认值（配置中的 `agents.defaults.thinkingDefault`）。
|
||||
5. 回退：如果可用，则使用 provider 声明的默认值；否则，支持推理的模型会解析为 `medium` 或该模型支持的最接近的非 `off` 级别，不支持推理的模型则保持 `off`。
|
||||
5. 回退：如果可用，则使用提供商声明的默认值；否则，支持推理的模型会解析为 `medium` 或该模型最接近的受支持非 `off` 级别，不支持推理的模型则保持为 `off`。
|
||||
|
||||
## 设置会话默认值
|
||||
|
||||
- 发送一条**仅包含指令**的消息（允许空白字符），例如 `/think:medium` 或 `/t high`。
|
||||
- 该设置会在当前会话中保持生效（默认按发送者区分）；可通过 `/think:off` 或会话空闲重置来清除。
|
||||
- 会发送确认回复（`Thinking level set to high.` / `Thinking disabled.`）。如果级别无效（例如 `/thinking big`），命令会被拒绝，并给出提示，同时不会更改会话状态。
|
||||
- 发送不带参数的 `/think`（或 `/think:`）即可查看当前思考级别。
|
||||
- 发送一条**仅包含该指令**的消息（允许空白字符），例如 `/think:medium` 或 `/t high`。
|
||||
- 这会在当前会话中持续生效（默认按发送者区分）；可通过 `/think:off` 或会话空闲重置来清除。
|
||||
- 会发送确认回复（`Thinking level set to high.` / `Thinking disabled.`）。如果级别无效（例如 `/thinking big`），命令会被拒绝并给出提示，会话状态保持不变。
|
||||
- 发送不带参数的 `/think`（或 `/think:`）可查看当前思考级别。
|
||||
|
||||
## 按智能体应用
|
||||
|
||||
- **嵌入式 Pi**：解析后的级别会传递给进程内的 Pi 智能体运行时。
|
||||
- **嵌入式 Pi**：解析后的级别会传递给进程内 Pi 智能体运行时。
|
||||
|
||||
## 快速模式（`/fast`）
|
||||
|
||||
- 级别：`on|off`。
|
||||
- 仅含指令的消息会切换会话快速模式覆盖值，并回复 `Fast mode enabled.` / `Fast mode disabled.`。
|
||||
- 发送不带模式的 `/fast`（或 `/fast status`）即可查看当前生效的快速模式状态。
|
||||
- 仅指令消息会切换会话快速模式覆盖，并回复 `Fast mode enabled.` / `Fast mode disabled.`。
|
||||
- 发送不带模式的 `/fast`（或 `/fast status`）可查看当前生效的快速模式状态。
|
||||
- OpenClaw 按以下顺序解析快速模式：
|
||||
1. 内联/仅指令 `/fast on|off`
|
||||
2. 会话覆盖值
|
||||
1. 内联 / 仅指令 `/fast on|off`
|
||||
2. 会话覆盖
|
||||
3. 每个智能体的默认值（`agents.list[].fastModeDefault`）
|
||||
4. 每个模型的配置：`agents.defaults.models["<provider>/<model>"].params.fastMode`
|
||||
5. 回退：`off`
|
||||
- 对于 `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`。
|
||||
- 对于 `openai/*`，快速模式会通过在支持的 Responses 请求上发送 `service_tier=priority` 映射到 OpenAI 优先处理。
|
||||
- 对于 `openai-codex/*`，快速模式会在 Codex Responses 上发送相同的 `service_tier=priority` 标志。OpenClaw 会在两种凭证路径之间共享同一个 `/fast` 切换。
|
||||
- 对于直接公共的 `anthropic/*` 请求，包括发送到 `api.anthropic.com` 的 OAuth 认证流量，快速模式会映射到 Anthropic service tiers：`/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 服务层级。
|
||||
- 当 Anthropic 的显式 `serviceTier` / `service_tier` 模型参数与快速模式默认值同时设置时，前者会覆盖后者。对于非 Anthropic 代理 base URL，OpenClaw 仍会跳过 Anthropic service-tier 注入。
|
||||
- 仅当快速模式启用时，`/status` 才会显示 `Fast`。
|
||||
|
||||
## 详细模式指令（`/verbose` 或 `/v`）
|
||||
## 详细指令（`/verbose` 或 `/v`）
|
||||
|
||||
- 级别：`on`（最简）| `full` | `off`（默认）。
|
||||
- 仅含指令的消息会切换会话详细模式，并回复 `Verbose logging enabled.` / `Verbose logging disabled.`；无效级别会返回提示，但不会更改状态。
|
||||
- `/verbose off` 会存储一个显式的会话覆盖值；可在 Sessions UI 中选择 `inherit` 来清除它。
|
||||
- 内联指令仅对该条消息生效；否则会应用会话/全局默认值。
|
||||
- 发送不带参数的 `/verbose`（或 `/verbose:`）即可查看当前详细级别。
|
||||
- 当 verbose 开启时，会输出结构化工具结果的智能体（Pi、其他 JSON 智能体）会将每次工具调用作为单独的仅元数据消息发回；如果可用，会以 `<emoji> <tool-name>: <arg>` 作为前缀（路径/命令）。这些工具摘要会在每个工具启动时立即发送（独立消息气泡），而不是作为流式增量发送。
|
||||
- 工具失败摘要在普通模式下仍然可见，但除非 verbose 为 `on` 或 `full`，否则会隐藏原始错误详情后缀。
|
||||
- 当 verbose 为 `full` 时，工具输出也会在完成后转发（独立消息气泡，截断到安全长度）。如果你在运行过程中切换 `/verbose on|full|off`，后续的工具消息气泡会遵循新的设置。
|
||||
- 级别：`on`（最小）| `full` | `off`（默认）。
|
||||
- 仅指令消息会切换会话详细模式，并回复 `Verbose logging enabled.` / `Verbose logging disabled.`；无效级别会返回提示且不改变状态。
|
||||
- `/verbose off` 会存储一个显式的会话覆盖；可在会话 UI 中选择 `inherit` 来清除。
|
||||
- 内联指令仅影响该条消息；否则应用会话 / 全局默认值。
|
||||
- 发送不带参数的 `/verbose`（或 `/verbose:`）可查看当前详细级别。
|
||||
- 当 verbose 为开启时，会输出结构化工具结果的智能体（Pi、其他 JSON 智能体）会将每次工具调用作为单独的仅元数据消息发回，并在可用时以前缀 `<emoji> <tool-name>: <arg>` 显示（路径 / 命令）。这些工具摘要会在每个工具启动时立即发送（独立气泡），而不是作为流式增量发送。
|
||||
- 工具失败摘要在普通模式下仍然可见，但原始错误详情后缀只有在 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`）
|
||||
|
||||
- 级别：`on|off|stream`。
|
||||
- 仅含指令的消息会切换是否在回复中显示 thinking 块。
|
||||
- 启用后，推理会作为**单独一条消息**发送，并以 `Reasoning:` 为前缀。
|
||||
- `stream`（仅限 Telegram）：会在回复生成期间将推理流式写入 Telegram 草稿气泡，随后发送不含推理的最终答案。
|
||||
- 仅指令消息会切换是否在回复中显示思考块。
|
||||
- 启用后，推理会作为一条**单独消息**发送，并以 `Reasoning:` 为前缀。
|
||||
- `stream`（仅 Telegram）：在生成回复时，将推理流式输出到 Telegram 草稿气泡中，然后发送不包含推理的最终答案。
|
||||
- 别名：`/reason`。
|
||||
- 发送不带参数的 `/reasoning`（或 `/reasoning:`）即可查看当前推理级别。
|
||||
- 解析顺序：内联指令，然后是会话覆盖值，再然后是每个智能体的默认值（`agents.list[].reasoningDefault`），最后回退为 `off`。
|
||||
- 发送不带参数的 `/reasoning`（或 `/reasoning:`）可查看当前推理级别。
|
||||
- 解析顺序：内联指令，然后是会话覆盖，然后是每个智能体默认值（`agents.list[].reasoningDefault`），最后是回退（`off`）。
|
||||
|
||||
格式错误的本地模型推理标签会被保守处理。闭合的 `<think>...</think>` 块在普通回复中会保持隐藏；在已有可见文本之后出现的未闭合推理内容也会被隐藏。如果回复整体被单个未闭合起始标签包裹，且否则会导致发送空文本，OpenClaw 会移除这个格式错误的起始标签，并发送剩余文本。
|
||||
对于格式错误的本地模型推理标签，会采用保守处理方式。闭合的 `<think>...</think>` 块在普通回复中保持隐藏，而在已出现可见文本之后出现的未闭合推理内容也会隐藏。如果某条回复完全被单个未闭合的起始标签包裹，并且否则会导致发送空文本，OpenClaw 会移除这个格式错误的起始标签，并发送剩余文本。
|
||||
|
||||
## 相关内容
|
||||
|
||||
- Elevated mode 文档见 [Elevated mode](/zh-CN/tools/elevated)。
|
||||
- Elevated mode 文档位于 [Elevated mode](/zh-CN/tools/elevated)。
|
||||
|
||||
## Heartbeats
|
||||
## 心跳
|
||||
|
||||
- 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`。
|
||||
- 心跳探测消息体为已配置的心跳提示（默认值：`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.`）。心跳消息中的内联指令会照常生效（但应避免通过心跳更改会话默认值）。
|
||||
- 心跳传递默认只发送最终 payload。若还要发送单独的 `Reasoning:` 消息（如果可用），请设置 `agents.defaults.heartbeat.includeReasoning: true` 或每个智能体的 `agents.list[].heartbeat.includeReasoning: true`。
|
||||
|
||||
## Web 聊天 UI
|
||||
|
||||
- Web 聊天中的思考选择器会在页面加载时，镜像入站会话存储/配置中该会话的已存储级别。
|
||||
- 选择其他级别会立即通过 `sessions.patch` 写入会话覆盖值；它不会等待下一次发送，也不是一次性的 `thinkingOnce` 覆盖。
|
||||
- 第一个选项始终是 `Default (<resolved level>)`，其中解析后的默认值来自活动会话模型的 provider thinking 配置文件，以及 `/status` 和 `session_status` 使用的同一套回退逻辑。
|
||||
- 选择器使用 Gateway 网关 会话行/默认值返回的 `thinkingLevels`，并保留 `thinkingOptions` 作为旧版标签列表。浏览器 UI 不会维护自己的 provider 正则列表；模型专属级别集由插件负责。
|
||||
- `/think:<level>` 仍然可用，并会更新相同的已存储会话级别，因此聊天指令与选择器始终保持同步。
|
||||
- Web 聊天思考选择器在页面加载时，会从入站会话存储 / 配置中镜像该会话已存储的级别。
|
||||
- 选择其他级别会立即通过 `sessions.patch` 写入会话覆盖；它不会等到下一次发送，也不是一次性的 `thinkingOnce` 覆盖。
|
||||
- 第一个选项始终是 `Default (<resolved level>)`，其中解析后的默认值来自活动会话模型的提供商思考配置文件，以及 `/status` 和 `session_status` 使用的相同回退逻辑。
|
||||
- 选择器使用 Gateway 网关会话行 / 默认值返回的 `thinkingLevels`，并将 `thinkingOptions` 保留为旧版标签列表。浏览器 UI 不会维护自己的提供商正则列表；模型特定的级别集合由插件负责。
|
||||
- `/think:<level>` 仍然有效，并会更新同一个已存储的会话级别，因此聊天指令和选择器会保持同步。
|
||||
|
||||
## 提供商配置文件
|
||||
|
||||
- 提供商插件可暴露 `resolveThinkingProfile(ctx)` 以定义模型支持的级别和默认值。
|
||||
- 提供商插件可以暴露 `resolveThinkingProfile(ctx)`，用于定义模型支持的级别及默认值。
|
||||
- 代理 Claude 模型的提供商插件应复用 `openclaw/plugin-sdk/provider-model-shared` 中的 `resolveClaudeThinkingProfile(modelId)`，以便让直接 Anthropic 和代理 catalog 保持一致。
|
||||
- 每个配置文件级别都有一个已存储的规范 `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 和标签。
|
||||
- 需要校验显式思考覆盖的工具插件应使用 `api.runtime.agent.resolveThinkingPolicy({ provider, model })` 加 `api.runtime.agent.normalizeThinkingLevel(...)`；它们不应维护自己的提供商 / 模型级别列表。
|
||||
- 已发布的旧版钩子（`supportsXHighThinking`、`isBinaryThinking` 和 `resolveDefaultThinkingLevel`）仍作为兼容性适配器保留，但新的自定义级别集合应使用 `resolveThinkingProfile`。
|
||||
- Gateway 网关行 / 默认值会暴露 `thinkingLevels`、`thinkingOptions` 和 `thinkingDefault`，这样 ACP / 聊天客户端就能渲染与运行时校验相同的配置文件 id 和标签。
|
||||
|
||||
@ -1,29 +1,29 @@
|
||||
---
|
||||
read_when:
|
||||
- 你想通过浏览器操作 Gateway 网关
|
||||
- 你希望在不使用 SSH 隧道的情况下通过 Tailnet 访问
|
||||
- 你想要无需 SSH 隧道的 Tailnet 访问
|
||||
sidebarTitle: Control UI
|
||||
summary: Gateway 网关 的基于浏览器的 Control UI（聊天、节点、配置）
|
||||
title: Control UI
|
||||
summary: 基于浏览器的 Gateway 网关控制 UI（聊天、节点、配置）
|
||||
title: 控制 UI
|
||||
x-i18n:
|
||||
generated_at: "2026-04-27T09:30:28Z"
|
||||
generated_at: "2026-04-27T13:32:13Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 062128bc66e63b768f4088a935a8850ce3c61e6c431ee5ef0567e5a93d579878
|
||||
source_hash: 8a438d96e3df280d72106f4d48b5989afb1675a6c075e0688c4b2f4363433d3d
|
||||
source_path: web/control-ui.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
Control UI 是一个由 Gateway 网关 提供服务的小型 **Vite + Lit** 单页应用：
|
||||
Control UI 是一个小型的 **Vite + Lit** 单页应用，由 Gateway 网关提供服务：
|
||||
|
||||
- 默认：`http://<host>:18789/`
|
||||
- 默认地址：`http://<host>:18789/`
|
||||
- 可选前缀：设置 `gateway.controlUi.basePath`（例如 `/openclaw`）
|
||||
|
||||
它会在同一端口上**直接连接到 Gateway 网关 WebSocket**。
|
||||
|
||||
## 快速打开（本地）
|
||||
|
||||
如果 Gateway 网关 运行在同一台电脑上，请打开：
|
||||
如果 Gateway 网关运行在同一台电脑上，请打开：
|
||||
|
||||
- [http://127.0.0.1:18789/](http://127.0.0.1:18789/)（或 [http://localhost:18789/](http://localhost:18789/)）
|
||||
|
||||
@ -33,16 +33,16 @@ Control UI 是一个由 Gateway 网关 提供服务的小型 **Vite + Lit** 单
|
||||
|
||||
- `connect.params.auth.token`
|
||||
- `connect.params.auth.password`
|
||||
- 当 `gateway.auth.allowTailscale: true` 时使用 Tailscale Serve 身份请求头
|
||||
- 当 `gateway.auth.mode: "trusted-proxy"` 时使用受信任代理身份请求头
|
||||
- 当 `gateway.auth.allowTailscale: true` 时使用 Tailscale Serve 身份头
|
||||
- 当 `gateway.auth.mode: "trusted-proxy"` 时使用 trusted-proxy 身份头
|
||||
|
||||
仪表板设置面板会为当前浏览器标签页会话保存 token 和所选的 gateway URL；密码不会被持久化。新手引导通常会在首次连接时为共享密钥认证生成一个 gateway token，但当 `gateway.auth.mode` 为 `"password"` 时，也可以使用密码认证。
|
||||
仪表板设置面板会为当前浏览器标签页会话和所选 Gateway 网关 URL 保存一个令牌；密码不会被持久化。新手引导通常会在首次连接时为共享密钥认证生成一个 Gateway 网关令牌，但当 `gateway.auth.mode` 为 `"password"` 时，密码认证同样可用。
|
||||
|
||||
## 设备配对（首次连接）
|
||||
|
||||
当你从新的浏览器或设备连接到 Control UI 时，Gateway 网关 通常会要求进行**一次性配对批准**。这是一项安全措施，用于防止未经授权的访问。
|
||||
当你从新的浏览器或设备连接到 Control UI 时，Gateway 网关通常会要求进行**一次性配对批准**。这是一项安全措施，用于防止未授权访问。
|
||||
|
||||
**你会看到的内容：** “disconnected (1008): pairing required”
|
||||
**你会看到：** “disconnected (1008): pairing required”
|
||||
|
||||
<Steps>
|
||||
<Step title="列出待处理请求">
|
||||
@ -57,160 +57,162 @@ Control UI 是一个由 Gateway 网关 提供服务的小型 **Vite + Lit** 单
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
如果浏览器在认证详情发生变化（角色/作用域/公钥）后重试配对，之前的待处理请求会被替换，并创建新的 `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>` 撤销它，否则无需再次批准。有关令牌轮换和撤销，请参见 [Devices CLI](/zh-CN/cli/devices)。
|
||||
|
||||
<Note>
|
||||
- 直接本地 local loopback 浏览器连接（`127.0.0.1` / `localhost`）会自动获批。
|
||||
- 当 `gateway.auth.allowTailscale: true`、Tailscale 身份校验通过且浏览器出示其设备身份时，Tailscale Serve 可以为 Control UI 操作员会话跳过配对往返过程。
|
||||
- 直接 Tailnet 绑定、LAN 浏览器连接以及没有设备身份的浏览器配置文件，仍然需要显式批准。
|
||||
- 直接本地 local loopback 浏览器连接（`127.0.0.1` / `localhost`）会被自动批准。
|
||||
- 当 `gateway.auth.allowTailscale: true`、Tailscale 身份验证通过且浏览器提供其设备身份时，Tailscale Serve 可为 Control UI 操作员会话跳过配对往返流程。
|
||||
- 直接 Tailnet 绑定、LAN 浏览器连接，以及没有设备身份的浏览器配置文件，仍然需要显式批准。
|
||||
- 每个浏览器配置文件都会生成唯一的设备 ID，因此切换浏览器或清除浏览器数据都需要重新配对。
|
||||
</Note>
|
||||
|
||||
## 个人身份（浏览器本地）
|
||||
|
||||
Control UI 支持按浏览器设置个人身份（显示名称和头像），它会附加到发出的消息上，以便在共享会话中标注归属。它存储在浏览器存储中，作用域限于当前浏览器配置文件，不会同步到其他设备，也不会在服务端持久化；只有你实际发送的消息，其正常转录作者元数据会保留下来。清除站点数据或切换浏览器会将其重置为空。
|
||||
Control UI 支持每个浏览器独立的个人身份（显示名称和头像），会附加到发出的消息上，以便在共享会话中进行归属标识。它保存在浏览器存储中，仅限当前浏览器配置文件使用，不会同步到其他设备，也不会在服务端持久化，除了你实际发送的消息所附带的常规转录作者元数据。清除站点数据或切换浏览器会将其重置为空。
|
||||
|
||||
同样的浏览器本地模式也适用于助手头像覆盖。上传的助手头像只会在本地浏览器中覆盖 gateway 解析出的身份，绝不会通过 `config.patch` 往返传输。共享的 `ui.assistant.avatar` 配置字段仍可供直接写入该字段的非 UI 客户端使用（例如脚本化 gateway 或自定义仪表板）。
|
||||
同样的浏览器本地模式也适用于助手头像覆盖。上传的助手头像只会在本地浏览器中覆盖 Gateway 网关解析出的身份，绝不会通过 `config.patch` 往返传输。共享的 `ui.assistant.avatar` 配置字段仍可用于直接写入该字段的非 UI 客户端（例如脚本化 Gateway 网关或自定义仪表板）。
|
||||
|
||||
## 运行时配置端点
|
||||
|
||||
Control UI 会从 `/__openclaw/control-ui-config.json` 获取其运行时设置。该端点受与其余 HTTP 接口相同的 gateway 认证保护：未经认证的浏览器无法获取它，而成功获取需要已有效的 gateway token/密码、Tailscale Serve 身份或受信任代理身份之一。
|
||||
Control UI 会从 `/__openclaw/control-ui-config.json` 获取其运行时设置。该端点与其余 HTTP 接口一样受相同的 Gateway 网关认证保护：未认证的浏览器无法获取它，而成功获取需要已有有效的 Gateway 网关令牌 / 密码、Tailscale Serve 身份，或 trusted-proxy 身份。
|
||||
|
||||
## 语言支持
|
||||
|
||||
Control UI 可在首次加载时根据你的浏览器语言环境进行本地化。若之后要覆盖它，请打开 **Overview -> Gateway Access -> Language**。语言选择器位于 Gateway Access 卡片中，而不是 Appearance 下。
|
||||
Control UI 可以在首次加载时根据你的浏览器语言环境进行本地化。若之后要覆盖它，请打开 **概览 -> 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`
|
||||
- 非英文翻译会在浏览器中按需延迟加载。
|
||||
- 所选语言环境会保存在浏览器存储中，并在之后访问时复用。
|
||||
- 缺失的翻译键会回退到英文。
|
||||
|
||||
## 当前可执行的操作
|
||||
## 它目前能做什么
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="聊天和 Talk">
|
||||
- 通过 Gateway WS 与模型聊天（`chat.history`, `chat.send`, `chat.abort`, `chat.inject`）。
|
||||
- 通过 WebRTC 直接从浏览器连接到 OpenAI Realtime 进行 Talk。Gateway 网关 使用 `talk.realtime.session` 签发短期有效的 Realtime 客户端密钥；浏览器将麦克风音频直接发送到 OpenAI，并通过 `chat.send` 将 `openclaw_agent_consult` 工具调用中继回去，以供已配置的更大型 OpenClaw 模型处理。
|
||||
<Accordion title="聊天和通话">
|
||||
- 通过 Gateway 网关 WS 与模型聊天（`chat.history`、`chat.send`、`chat.abort`、`chat.inject`）。
|
||||
- 通过浏览器实时会话进行通话。OpenAI 使用直接 WebRTC，Google Live 通过 WebSocket 使用受限的一次性浏览器令牌，而仅后端实时语音插件则使用 Gateway 网关中继传输。中继会将提供商凭证保留在 Gateway 网关上，同时浏览器通过 `talk.realtime.relay*` RPC 流式传输麦克风 PCM，并通过 `chat.send` 将 `openclaw_agent_consult` 工具调用发回，以供配置好的更大型 OpenClaw 模型使用。
|
||||
- 在聊天中流式显示工具调用和实时工具输出卡片（智能体事件）。
|
||||
</Accordion>
|
||||
<Accordion title="渠道、实例、会话、Dreaming">
|
||||
- 渠道：内置渠道以及内置/外部插件渠道的状态、二维码登录和按渠道配置（`channels.status`, `web.login.*`, `config.patch`）。
|
||||
- 实例：在线列表和刷新（`system-presence`）。
|
||||
- 会话：列出会话，以及按会话覆盖模型/thinking/fast/verbose/trace/reasoning（`sessions.list`, `sessions.patch`）。
|
||||
- Dreaming：Dreaming 状态、启用/禁用开关，以及 Dream Diary 读取器（`doctor.memory.status`, `doctor.memory.dreamDiary`, `config.patch`）。
|
||||
- 渠道：内置渠道以及内置 / 外部插件渠道状态、QR 登录和按渠道配置（`channels.status`、`web.login.*`、`config.patch`）。
|
||||
- 实例：在线状态列表和刷新（`system-presence`）。
|
||||
- 会话：列表和按会话设置的模型 / 思考 / 快速 / 详细 / 跟踪 / 推理覆盖（`sessions.list`、`sessions.patch`）。
|
||||
- Dreaming：Dreaming 状态、启用 / 禁用切换和 Dream Diary 读取器（`doctor.memory.status`、`doctor.memory.dreamDiary`、`config.patch`）。
|
||||
</Accordion>
|
||||
<Accordion title="cron、Skills、节点、exec 批准">
|
||||
- cron 作业：列出/添加/编辑/运行/启用/禁用，以及运行历史（`cron.*`）。
|
||||
- Skills：状态、启用/禁用、安装、API key 更新（`skills.*`）。
|
||||
- 节点：列表和能力（`node.list`）。
|
||||
- exec 批准：编辑 gateway 或节点 allowlist，并为 `exec host=gateway/node` 询问策略（`exec.approvals.*`）。
|
||||
<Accordion title="Cron、Skills、节点、exec 批准">
|
||||
- Cron 任务：列表 / 添加 / 编辑 / 运行 / 启用 / 禁用 + 运行历史（`cron.*`）。
|
||||
- Skills：状态、启用 / 禁用、安装、API 密钥更新（`skills.*`）。
|
||||
- 节点：列表 + 能力（`node.list`）。
|
||||
- exec 批准：编辑 Gateway 网关或节点允许列表 + 为 `exec host=gateway/node` 设置询问策略（`exec.approvals.*`）。
|
||||
</Accordion>
|
||||
<Accordion title="配置">
|
||||
- 查看/编辑 `~/.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 提示、直接子项摘要、嵌套对象/通配符/数组/组合节点上的文档元数据，以及在可用时包含插件和渠道 schema）；仅当快照支持安全的原始往返时，原始 JSON 编辑器才可用。
|
||||
- 如果某个快照无法安全地往返原始文本，Control UI 会强制使用表单模式，并为该快照禁用原始模式。
|
||||
- 原始 JSON 编辑器中的“重置为已保存”会保留原始编写的形态（格式、注释、`$include` 布局），而不是重新渲染展平后的快照，因此当快照可以安全往返时，外部编辑在重置后仍会保留。
|
||||
- 结构化 SecretRef 对象值会在表单文本输入框中以只读方式渲染，以防意外将对象损坏为字符串。
|
||||
- 查看 / 编辑 `~/.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 提示、直接子项摘要、嵌套对象 / 通配符 / 数组 / 组合节点上的文档元数据，以及可用时的插件 + 渠道 schema）；仅当快照支持安全的原始往返时，才提供 Raw JSON 编辑器。
|
||||
- 如果某个快照无法安全地进行原始往返，Control UI 会强制使用表单模式，并对该快照禁用 Raw 模式。
|
||||
- Raw JSON 编辑器中的“重置为已保存”会保留原始编写的形状（格式、注释、`$include` 布局），而不是重新渲染扁平化快照，因此当快照可安全往返时，外部编辑在重置后仍能保留。
|
||||
- 结构化 SecretRef 对象值会在表单文本输入中以只读方式呈现，以防意外将对象破坏性地转换为字符串。
|
||||
</Accordion>
|
||||
<Accordion title="调试、日志、更新">
|
||||
- 调试：Status/健康/Models 快照 + 事件日志 + 手动 RPC 调用（`status`, `health`, `models.list`）。
|
||||
- 日志：实时跟踪 gateway 文件日志，并支持过滤/导出（`logs.tail`）。
|
||||
- 更新：运行 package/git 更新并重启（`update.run`），附带重启报告，然后在重连后轮询 `update.status` 以验证正在运行的 gateway 版本。
|
||||
- 调试：状态 / 健康 / 模型快照 + 事件日志 + 手动 RPC 调用（`status`、`health`、`models.list`）。
|
||||
- 日志：带过滤 / 导出的 Gateway 网关文件日志实时 tail（`logs.tail`）。
|
||||
- 更新：运行包 / git 更新 + 重启（`update.run`），附带重启报告，然后在重新连接后轮询 `update.status` 以确认正在运行的 Gateway 网关版本。
|
||||
</Accordion>
|
||||
<Accordion title="cron 作业面板说明">
|
||||
- 对于隔离作业，交付默认是公告摘要。如果你只想进行内部运行，也可以切换为 none。
|
||||
- 选择公告时，会显示渠道/目标字段。
|
||||
- webhook 模式使用 `delivery.mode = "webhook"`，并将 `delivery.to` 设置为有效的 HTTP(S) webhook URL。
|
||||
- 对于主会话作业，webhook 和 none 交付模式都可用。
|
||||
- 高级编辑控件包括运行后删除、清除智能体覆盖、cron 精确/错开选项、智能体模型/thinking 覆盖，以及尽力交付切换。
|
||||
- 表单校验会以内联方式显示字段级错误；在修复前，无效值会禁用保存按钮。
|
||||
- 设置 `cron.webhookToken` 可发送专用 bearer token；如果省略，则 webhook 将在不带认证请求头的情况下发送。
|
||||
- 已弃用的回退：已存储的旧版作业若使用 `notify: true`，在迁移前仍可使用 `cron.webhook`。
|
||||
<Accordion title="Cron 任务面板说明">
|
||||
- 对于隔离任务，投递默认是发布摘要。如果你希望仅内部运行，可以切换为 none。
|
||||
- 选择 announce 时会显示渠道 / 目标字段。
|
||||
- Webhook 模式使用 `delivery.mode = "webhook"`，并将 `delivery.to` 设置为有效的 HTTP(S) webhook URL。
|
||||
- 对于主会话任务，可用 webhook 和 none 投递模式。
|
||||
- 高级编辑控件包括运行后删除、清除智能体覆盖、cron 精确 / 错开选项、智能体模型 / 思考覆盖，以及尽力投递切换。
|
||||
- 表单验证为内联显示，并提供字段级错误；无效值会禁用保存按钮，直到修复为止。
|
||||
- 设置 `cron.webhookToken` 可发送专用 bearer 令牌；如果省略，则 webhook 在发送时不会带认证头。
|
||||
- 已弃用的回退方式：存储的旧版任务在 `notify: true` 时，迁移前仍可使用 `cron.webhook`。
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## 聊天行为
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="发送和历史语义">
|
||||
- `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.history` 短暂返回较旧快照，聊天视图会保持本地乐观的用户/助手消息可见；一旦 Gateway 网关 历史追上，规范转录就会替换这些本地消息。
|
||||
- `chat.inject` 会将一条助手注释追加到会话转录中，并广播一个 `chat` 事件用于仅 UI 的更新（不触发智能体运行，也不进行渠道投递）。
|
||||
- 聊天头部中的模型和 thinking 选择器会通过 `sessions.patch` 立即修补活跃会话；它们是持久的会话覆盖，而不是仅对单轮发送生效的选项。
|
||||
- 当新的 Gateway 网关 会话使用情况报告显示上下文压力较高时，聊天编辑区会显示上下文提示；在建议的压缩级别下，还会出现一个 compact 按钮，用于运行正常的会话压缩路径。在 Gateway 网关 再次报告新鲜使用情况之前，过时的 token 快照会被隐藏。
|
||||
<Accordion title="发送和历史记录语义">
|
||||
- `chat.send` 是**非阻塞**的：它会立即确认并返回 `{ runId, status: "started" }`，响应则通过 `chat` 事件流式传输。
|
||||
- 聊天上传支持图片以及非视频文件。图片保留原生图片路径；其他文件会存储为受管媒体，并在历史记录中显示为附件链接。
|
||||
- 使用相同的 `idempotencyKey` 重新发送时，如果仍在运行中会返回 `{ status: "in_flight" }`，完成后则返回 `{ status: "ok" }`。
|
||||
- `chat.history` 响应会受到大小限制，以保证 UI 安全。当转录条目过大时，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 / 全角模型控制标记，并省略那些其全部可见文本仅为精确静默标记 `NO_REPLY` / `no_reply` 的助手条目。
|
||||
- 在发送进行中以及最终刷新历史记录时，如果 `chat.history` 暂时返回较旧的快照，聊天视图会保留本地乐观显示的用户 / 助手消息；一旦 Gateway 网关历史记录追上，这些本地消息就会被规范转录替换。
|
||||
- `chat.inject` 会向会话转录追加一条助手备注，并广播 `chat` 事件用于仅 UI 更新（不运行智能体，也不投递到渠道）。
|
||||
- 聊天头部的模型和思考选择器会通过 `sessions.patch` 立即修补活动会话；它们是持久的会话覆盖，而不是仅单轮发送选项。
|
||||
- 当最新的 Gateway 网关会话用量报告显示上下文压力较高时，聊天编辑区会显示上下文提示；在建议进行压缩的级别下，还会显示一个 compact 按钮，用于执行常规会话压缩流程。过期的令牌快照会被隐藏，直到 Gateway 网关再次报告新的用量信息。
|
||||
</Accordion>
|
||||
<Accordion title="Talk 模式（浏览器 WebRTC）">
|
||||
Talk 模式使用已注册的实时语音提供商，该提供商支持浏览器 WebRTC 会话。可通过设置 `talk.provider: "openai"` 加上 `talk.providers.openai.apiKey` 来配置 OpenAI，或者复用 Voice Call 的实时提供商配置。浏览器绝不会收到标准的 OpenAI API key；它只会收到临时的 Realtime 客户端密钥。Google Live 实时语音支持后端 Voice Call 和 Google Meet 桥接，但目前还不支持这个浏览器 WebRTC 路径。Realtime 会话提示词由 Gateway 网关 组装；`talk.realtime.session` 不接受调用方提供的指令覆盖。
|
||||
<Accordion title="通话模式（浏览器实时）">
|
||||
通话模式使用已注册的实时语音提供商。可使用 `talk.provider: "openai"` 加 `talk.providers.openai.apiKey` 配置 OpenAI，或使用 `talk.provider: "google"` 加 `talk.providers.google.apiKey` 配置 Google；Voice Call 实时提供商配置仍可复用为回退方案。浏览器绝不会收到标准提供商 API 密钥。OpenAI 会收到用于 WebRTC 的临时 Realtime 客户端密钥。Google Live 会收到一个一次性、受约束的 Live API 认证令牌，用于浏览器 WebSocket 会话；说明和工具声明会由 Gateway 网关锁定到该令牌中。仅暴露后端实时桥接的提供商会通过 Gateway 网关中继传输运行，因此凭证和厂商套接字会保留在服务端，而浏览器音频则通过已认证的 Gateway 网关 RPC 传输。Realtime 会话提示词由 Gateway 网关组装；`talk.realtime.session` 不接受调用方提供的指令覆盖。
|
||||
|
||||
在聊天编辑器中，Talk 控件是麦克风听写按钮旁边的波形按钮。Talk 启动时，编辑器状态行会显示 `Connecting Talk...`，音频连接后显示 `Talk live`，或者当实时工具调用通过 `chat.send` 咨询已配置的更大 OpenClaw 模型时显示 `Asking OpenClaw...`。
|
||||
在聊天编辑器中，通话控件是麦克风听写按钮旁边的波形按钮。通话开始时，编辑器状态行会显示 `Connecting Talk...`，然后在音频连接期间显示 `Talk live`，或在实时工具调用通过 `chat.send` 咨询已配置的更大 OpenClaw 模型时显示 `Asking OpenClaw...`。
|
||||
|
||||
维护者在线冒烟测试：`OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts` 会验证 OpenAI 浏览器 WebRTC SDP 交换、Google Live 受约束令牌浏览器 WebSocket 设置，以及使用虚拟麦克风媒体的 Gateway 网关中继浏览器适配器。该命令只输出提供商状态，不会记录任何密钥。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="停止和中止">
|
||||
- 点击 **Stop**（调用 `chat.abort`）。
|
||||
- 当某个运行处于活跃状态时，普通后续消息会进入队列。点击排队消息上的 **Steer**，可将该后续消息注入到当前运行中的轮次。
|
||||
- 输入 `/stop`（或单独的中止短语，如 `stop`、`stop action`、`stop run`、`stop openclaw`、`please stop`）以带外中止。
|
||||
- `chat.abort` 支持 `{ sessionKey }`（不需要 `runId`）来中止该会话的所有活跃运行。
|
||||
- 点击**停止**（调用 `chat.abort`）。
|
||||
- 当某个运行处于活动状态时，普通后续消息会进入队列。点击排队消息上的**Steer** 可将该后续消息注入当前运行轮次。
|
||||
- 输入 `/stop`（或独立的中止短语，如 `stop`、`stop action`、`stop run`、`stop openclaw`、`please stop`）可进行带外中止。
|
||||
- `chat.abort` 支持 `{ sessionKey }`（无需 `runId`）以中止该会话的所有活动运行。
|
||||
</Accordion>
|
||||
<Accordion title="中止后的部分内容保留">
|
||||
- 当某个运行被中止时，UI 中仍可能显示部分助手文本。
|
||||
- 当存在缓冲输出时，Gateway 网关 会将被中止的部分助手文本持久化到转录历史中。
|
||||
- 持久化条目包含中止元数据，因此转录使用方可以区分中止的部分内容和正常完成输出。
|
||||
<Accordion title="中止后的部分保留">
|
||||
- 当某个运行被中止时，部分助手文本仍可能显示在 UI 中。
|
||||
- 当存在缓冲输出时，Gateway 网关会将中止时的部分助手文本持久化到转录历史中。
|
||||
- 持久化条目会包含中止元数据，以便转录消费者区分中止部分内容和正常完成输出。
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## PWA 安装和 Web Push
|
||||
|
||||
Control UI 附带了 `manifest.webmanifest` 和 service worker，因此现代浏览器可以将其安装为独立的 PWA。Web Push 让 Gateway 网关 即使在标签页或浏览器窗口未打开时，也能通过通知唤醒已安装的 PWA。
|
||||
Control UI 附带 `manifest.webmanifest` 和 service worker，因此现代浏览器可将其安装为独立的 PWA。Web Push 允许 Gateway 网关即使在标签页或浏览器窗口未打开时，也能通过通知唤醒已安装的 PWA。
|
||||
|
||||
| 界面 | 作用 |
|
||||
| ----------------------------------------------------- | ------------------------------------------------------------------ |
|
||||
| `ui/public/manifest.webmanifest` | PWA manifest。浏览器在其可访问后会提供“安装应用”。 |
|
||||
| `ui/public/manifest.webmanifest` | PWA 清单。浏览器在其可访问后会提供“安装应用”选项。 |
|
||||
| `ui/public/sw.js` | 处理 `push` 事件和通知点击的 service worker。 |
|
||||
| `push/vapid-keys.json`（位于 OpenClaw 状态目录下） | 自动生成的 VAPID 密钥对，用于对 Web Push 负载进行签名。 |
|
||||
| `push/web-push-subscriptions.json` | 持久化的浏览器订阅端点。 |
|
||||
|
||||
当你希望固定密钥时（多主机部署、密钥轮换或测试），可通过 Gateway 网关 进程上的环境变量覆盖 VAPID 密钥对：
|
||||
当你希望固定密钥对时（例如多主机部署、密钥轮换或测试），可通过 Gateway 网关进程上的环境变量覆盖 VAPID 密钥对：
|
||||
|
||||
- `OPENCLAW_VAPID_PUBLIC_KEY`
|
||||
- `OPENCLAW_VAPID_PRIVATE_KEY`
|
||||
- `OPENCLAW_VAPID_SUBJECT`（默认值为 `mailto:openclaw@localhost`）
|
||||
- `OPENCLAW_VAPID_SUBJECT`（默认为 `mailto:openclaw@localhost`）
|
||||
|
||||
Control UI 使用这些带作用域限制的 Gateway 网关 方法来注册和测试浏览器订阅：
|
||||
Control UI 使用以下受作用域限制的 Gateway 网关方法来注册和测试浏览器订阅：
|
||||
|
||||
- `push.web.vapidPublicKey` — 获取当前生效的 VAPID 公钥。
|
||||
- `push.web.subscribe` — 注册 `endpoint` 以及 `keys.p256dh`/`keys.auth`。
|
||||
- `push.web.unsubscribe` — 删除已注册的 endpoint。
|
||||
- `push.web.test` — 向调用方的订阅发送测试通知。
|
||||
- `push.web.vapidPublicKey` —— 获取当前活动的 VAPID 公钥。
|
||||
- `push.web.subscribe` —— 注册 `endpoint` 以及 `keys.p256dh` / `keys.auth`。
|
||||
- `push.web.unsubscribe` —— 删除已注册的端点。
|
||||
- `push.web.test` —— 向调用方的订阅发送测试通知。
|
||||
|
||||
<Note>
|
||||
Web Push 独立于 iOS APNS relay 路径（有关基于 relay 的推送，请参阅[配置](/zh-CN/gateway/configuration)）以及现有的 `push.test` 方法，后者针对原生移动端配对。
|
||||
Web Push 独立于 iOS APNS 中继路径（中继支持的推送请参见 [配置](/zh-CN/gateway/configuration)），也独立于现有的 `push.test` 方法，后者面向原生移动端配对。
|
||||
</Note>
|
||||
|
||||
## 托管嵌入
|
||||
|
||||
助手消息可以通过 `[embed ...]` 简码内联渲染托管的 Web 内容。iframe 沙箱策略由 `gateway.controlUi.embedSandbox` 控制：
|
||||
助手消息可通过 `[embed ...]` shortcode 内联渲染托管网页内容。iframe 沙箱策略由 `gateway.controlUi.embedSandbox` 控制：
|
||||
|
||||
<Tabs>
|
||||
<Tab title="strict">
|
||||
禁止在托管嵌入内容中执行脚本。
|
||||
禁止在托管嵌入中执行脚本。
|
||||
</Tab>
|
||||
<Tab title="scripts (default)">
|
||||
允许交互式嵌入，同时保持源隔离；这是默认值，通常足以支持自包含的浏览器游戏/小组件。
|
||||
允许交互式嵌入，同时保持源隔离；这是默认值，通常足以支持自包含的浏览器游戏 / 小部件。
|
||||
</Tab>
|
||||
<Tab title="trusted">
|
||||
在 `allow-scripts` 的基础上额外添加 `allow-same-origin`，用于那些确实需要更高权限的同站点文档。
|
||||
在 `allow-scripts` 的基础上增加 `allow-same-origin`，用于那些有意需要更高权限的同站文档。
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
@ -227,16 +229,16 @@ Web Push 独立于 iOS APNS relay 路径（有关基于 relay 的推送，请参
|
||||
```
|
||||
|
||||
<Warning>
|
||||
仅当嵌入文档确实需要同源行为时，才使用 `trusted`。对于大多数由智能体生成的游戏和交互式画布，`scripts` 是更安全的选择。
|
||||
仅当嵌入文档确实需要同源行为时才使用 `trusted`。对于大多数由智能体生成的游戏和交互式画布，`scripts` 是更安全的选择。
|
||||
</Warning>
|
||||
|
||||
绝对外部 `http(s)` 嵌入 URL 默认仍会被阻止。如果你有意让 `[embed url="https://..."]` 加载第三方页面，请设置 `gateway.controlUi.allowExternalEmbedUrls: true`。
|
||||
绝对外部 `http(s)` 嵌入 URL 默认仍会被阻止。如果你确实希望加载第三方页面的 `[embed url="https://..."]`，请设置 `gateway.controlUi.allowExternalEmbedUrls: true`。
|
||||
|
||||
## Tailnet 访问（推荐）
|
||||
|
||||
<Tabs>
|
||||
<Tab title="集成式 Tailscale Serve（首选）">
|
||||
让 Gateway 网关 保持在 loopback 上，并让 Tailscale Serve 通过 HTTPS 代理它：
|
||||
<Tab title="集成 Tailscale Serve（首选）">
|
||||
让 Gateway 网关保持绑定在 loopback 上，并由 Tailscale Serve 通过 HTTPS 进行代理：
|
||||
|
||||
```bash
|
||||
openclaw gateway --tailscale serve
|
||||
@ -246,12 +248,12 @@ Web Push 独立于 iOS APNS relay 路径（有关基于 relay 的推送，请参
|
||||
|
||||
- `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 时才会接受这些请求。对于具有浏览器设备身份的 Control UI 操作员会话，这条经过验证的 Serve 路径还会跳过设备配对往返过程；无设备浏览器和节点角色连接仍遵循正常设备检查。如果你希望即使对 Serve 流量也强制要求显式共享密钥凭证，请设置 `gateway.auth.allowTailscale: false`。然后使用 `gateway.auth.mode: "token"` 或 `"password"`。
|
||||
默认情况下，当 `gateway.auth.allowTailscale` 为 `true` 时，Control UI / WebSocket Serve 请求可通过 Tailscale 身份头（`tailscale-user-login`）进行认证。OpenClaw 会通过使用 `tailscale whois` 解析 `x-forwarded-for` 地址并与该头进行匹配来验证身份，且仅当请求命中 loopback 并带有 Tailscale 的 `x-forwarded-*` 头时才接受这些头。对于带有浏览器设备身份的 Control UI 操作员会话，这条经过验证的 Serve 路径还会跳过设备配对往返流程；无设备浏览器和节点角色连接仍会遵循正常的设备检查。如果你希望即使对 Serve 流量也要求显式共享密钥凭证，请将 `gateway.auth.allowTailscale` 设为 `false`。然后使用 `gateway.auth.mode: "token"` 或 `"password"`。
|
||||
|
||||
对于这条异步 Serve 身份路径，来自同一客户端 IP 和认证作用域的失败认证尝试，在写入限流记录之前会被串行化处理。因此，同一浏览器发起的并发错误重试中，第二个请求可能会显示 `retry later`，而不是两个普通不匹配并行竞争。
|
||||
对于该异步 Serve 身份路径，来自同一客户端 IP 和认证范围的失败认证尝试会在写入速率限制前被串行化。因此，同一浏览器的并发错误重试在第二个请求上可能会显示 `retry later`，而不是两个普通不匹配并行竞争。
|
||||
|
||||
<Warning>
|
||||
无 token 的 Serve 认证假定 gateway 主机是可信的。如果该主机上可能运行不可信的本地代码，请要求 token/密码认证。
|
||||
无令牌的 Serve 认证假定 gateway 主机是可信的。如果该主机上可能运行不受信任的本地代码，请要求使用 token / password 认证。
|
||||
</Warning>
|
||||
|
||||
</Tab>
|
||||
@ -271,15 +273,15 @@ Web Push 独立于 iOS APNS relay 路径（有关基于 relay 的推送，请参
|
||||
|
||||
## 不安全的 HTTP
|
||||
|
||||
如果你通过纯 HTTP 打开仪表板（`http://<lan-ip>` 或 `http://<tailscale-ip>`），浏览器会运行在**非安全上下文**中，并阻止 WebCrypto。默认情况下，OpenClaw **会阻止**没有设备身份的 Control UI 连接。
|
||||
如果你通过明文 HTTP 打开仪表板（`http://<lan-ip>` 或 `http://<tailscale-ip>`），浏览器会运行在**非安全上下文**中，并阻止 WebCrypto。默认情况下，OpenClaw 会**阻止**没有设备身份的 Control UI 连接。
|
||||
|
||||
文档化的例外情况：
|
||||
有文档记录的例外情况：
|
||||
|
||||
- 使用 `gateway.controlUi.allowInsecureAuth=true` 时，仅限 localhost 的不安全 HTTP 兼容模式
|
||||
- 通过 `gateway.auth.mode: "trusted-proxy"` 成功进行的操作员 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：
|
||||
**推荐修复方法：** 使用 HTTPS（Tailscale Serve）或在本地打开 UI：
|
||||
|
||||
- `https://<magicdns>/`（Serve）
|
||||
- `http://127.0.0.1:18789/`（在 gateway 主机上）
|
||||
@ -303,7 +305,7 @@ Web Push 独立于 iOS APNS relay 路径（有关基于 relay 的推送，请参
|
||||
- 它不会放宽远程（非 localhost）设备身份要求。
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="仅用于紧急兜底">
|
||||
<Accordion title="仅限破窗应急">
|
||||
```json5
|
||||
{
|
||||
gateway: {
|
||||
@ -315,67 +317,67 @@ Web Push 独立于 iOS APNS relay 路径（有关基于 relay 的推送，请参
|
||||
```
|
||||
|
||||
<Warning>
|
||||
`dangerouslyDisableDeviceAuth` 会禁用 Control UI 设备身份检查，这是严重的安全降级。紧急使用后请尽快恢复。
|
||||
`dangerouslyDisableDeviceAuth` 会禁用 Control UI 设备身份检查，这是严重的安全降级。仅在紧急使用后尽快恢复。
|
||||
</Warning>
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="受信任代理说明">
|
||||
<Accordion title="trusted-proxy 说明">
|
||||
- 成功的 trusted-proxy 认证可以允许**操作员** Control UI 会话在没有设备身份的情况下接入。
|
||||
- 这**不**适用于节点角色的 Control UI 会话。
|
||||
- 同主机 loopback 反向代理仍然不能满足 trusted-proxy 认证；请参阅[受信任代理认证](/zh-CN/gateway/trusted-proxy-auth)。
|
||||
- 同一主机上的 loopback 反向代理仍不满足 trusted-proxy 认证；参见 [Trusted proxy auth](/zh-CN/gateway/trusted-proxy-auth)。
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
有关 HTTPS 设置指导，请参阅 [Tailscale](/zh-CN/gateway/tailscale)。
|
||||
有关 HTTPS 设置指导，请参见 [Tailscale](/zh-CN/gateway/tailscale)。
|
||||
|
||||
## 内容安全策略
|
||||
|
||||
Control UI 内置了严格的 `img-src` 策略：只允许**同源**资源、`data:` URL 和本地生成的 `blob:` URL。远程 `http(s)` 和协议相对图片 URL 会被浏览器拒绝，且不会发起网络请求。
|
||||
Control UI 采用了严格的 `img-src` 策略：仅允许**同源**资源、`data:` URL 和本地生成的 `blob:` URL。远程 `http(s)` 和协议相对图片 URL 会被浏览器拒绝，并且不会发起网络请求。
|
||||
|
||||
这在实际中的含义：
|
||||
这在实践中意味着：
|
||||
|
||||
- 在相对路径下提供的头像和图片（例如 `/avatars/<id>`）仍然可以渲染，包括 UI 获取后转换为本地 `blob:` URL 的已认证头像路由。
|
||||
- 内联 `data:image/...` URL 仍然可以渲染（适用于协议内负载）。
|
||||
- 由 Control UI 创建的本地 `blob:` URL 仍然可以渲染。
|
||||
- 由渠道元数据发出的远程头像 URL 会在 Control UI 的头像辅助逻辑中被剥离，并替换为内置 logo/badge，因此即使渠道已被攻破或是恶意的，也无法强迫操作员浏览器发起任意远程图片请求。
|
||||
- 通过相对路径提供的头像和图片（例如 `/avatars/<id>`）仍可渲染，包括那些需要认证、由 UI 获取后转换为本地 `blob:` URL 的头像路由。
|
||||
- 内联 `data:image/...` URL 仍可渲染（这对协议内负载很有用）。
|
||||
- 由 Control UI 创建的本地 `blob:` URL 仍可渲染。
|
||||
- 渠道元数据发出的远程头像 URL 会在 Control UI 的头像辅助函数中被剥离，并替换为内置 logo / 徽标，因此即使渠道遭到入侵或具有恶意，也无法强制操作员浏览器发起任意远程图片请求。
|
||||
|
||||
你无需进行任何更改即可获得此行为——它始终启用，且不可配置。
|
||||
你无需做任何更改即可获得此行为 —— 它始终开启且不可配置。
|
||||
|
||||
## 头像路由认证
|
||||
|
||||
当配置了 gateway 认证时，Control UI 头像端点要求使用与 API 其余部分相同的 gateway token：
|
||||
配置了 Gateway 网关认证后，Control UI 头像端点需要与其余 API 相同的 Gateway 网关令牌：
|
||||
|
||||
- `GET /avatar/<agentId>` 仅向已认证调用方返回头像图片。`GET /avatar/<agentId>?meta=1` 在相同规则下返回头像元数据。
|
||||
- 对这两个路由的未认证请求都会被拒绝（与相邻的助手媒体路由保持一致）。这可防止头像路由在其他部分受保护的主机上泄露智能体身份。
|
||||
- Control UI 自身在获取头像时，会将 gateway token 作为 bearer 请求头转发，并使用已认证的 blob URL，因此图片仍可在仪表板中渲染。
|
||||
- 对任一路由的未认证请求都会被拒绝（与同级的助手媒体路由一致）。这可防止头像路由在其他受保护的主机上泄露智能体身份。
|
||||
- Control UI 本身在获取头像时会将 Gateway 网关令牌作为 bearer 头转发，并使用已认证的 blob URL，因此图片仍能在仪表板中渲染。
|
||||
|
||||
如果你禁用了 gateway 认证（不建议在共享主机上这样做），头像路由也会与 gateway 其余部分保持一致，变为未认证访问。
|
||||
如果你禁用了 Gateway 网关认证（不建议在共享主机上这样做），头像路由也会变为未认证状态，与 Gateway 网关的其余部分保持一致。
|
||||
|
||||
## 构建 UI
|
||||
|
||||
Gateway 网关 会从 `dist/control-ui` 提供静态文件。使用以下命令构建：
|
||||
Gateway 网关从 `dist/control-ui` 提供静态文件。使用以下命令构建它们：
|
||||
|
||||
```bash
|
||||
pnpm ui:build
|
||||
```
|
||||
|
||||
可选的绝对 base（当你想使用固定资源 URL 时）：
|
||||
可选绝对 base 路径（当你希望使用固定资源 URL 时）：
|
||||
|
||||
```bash
|
||||
OPENCLAW_CONTROL_UI_BASE_PATH=/openclaw/ pnpm ui:build
|
||||
```
|
||||
|
||||
用于本地开发（独立开发服务器）：
|
||||
本地开发时（单独的开发服务器）：
|
||||
|
||||
```bash
|
||||
pnpm ui:dev
|
||||
```
|
||||
|
||||
然后让 UI 指向你的 Gateway 网关 WS URL（例如 `ws://127.0.0.1:18789`）。
|
||||
然后将 UI 指向你的 Gateway 网关 WS URL（例如 `ws://127.0.0.1:18789`）。
|
||||
|
||||
## 调试/测试：开发服务器 + 远程 Gateway 网关
|
||||
## 调试 / 测试：开发服务器 + 远程 Gateway
|
||||
|
||||
Control UI 是静态文件；WebSocket 目标可配置，并且可以不同于 HTTP 源。当你希望在本地运行 Vite 开发服务器、但 Gateway 网关 运行在其他地方时，这非常有用。
|
||||
Control UI 是静态文件；WebSocket 目标可配置，并且可以不同于 HTTP 源。当你希望本地运行 Vite 开发服务器，而 Gateway 网关运行在其他地方时，这会很方便。
|
||||
|
||||
<Steps>
|
||||
<Step title="启动 UI 开发服务器">
|
||||
@ -399,16 +401,16 @@ Control UI 是静态文件；WebSocket 目标可配置，并且可以不同于 H
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="说明">
|
||||
- `gatewayUrl` 会在加载后存储到 `localStorage` 中，并从 URL 中移除。
|
||||
- 应尽可能通过 URL 片段（`#token=...`）传递 `token`。片段不会发送到服务器，这样可以避免请求日志和 Referer 泄露。为兼容旧方式，仍会一次性导入旧版 `?token=` 查询参数，但仅作为回退，并会在启动后立即剥离。
|
||||
- `gatewayUrl` 会在加载后存储到 localStorage 中，并从 URL 中移除。
|
||||
- 应尽可能通过 URL 片段（`#token=...`）传递 `token`。片段不会发送到服务器，因此可避免请求日志和 Referer 泄露。为兼容性起见，旧版 `?token=` 查询参数仍会被一次性导入，但仅作为回退方案，并会在引导后立即移除。
|
||||
- `password` 仅保存在内存中。
|
||||
- 设置 `gatewayUrl` 后，UI 不会回退到配置或环境变量凭证。请显式提供 `token`（或 `password`）。缺少显式凭证会报错。
|
||||
- 当 Gateway 网关 位于 TLS 后面时（Tailscale Serve、HTTPS 代理等），请使用 `wss://`。
|
||||
- `gatewayUrl` 仅在顶层窗口中接受（不能嵌入），以防止点击劫持。
|
||||
- 设置了 `gatewayUrl` 时，UI 不会回退到配置或环境凭证。请显式提供 `token`（或 `password`）。缺少显式凭证会报错。
|
||||
- 当 Gateway 网关位于 TLS 之后时（Tailscale Serve、HTTPS 代理等），请使用 `wss://`。
|
||||
- `gatewayUrl` 仅在顶级窗口中接受（不能嵌入），以防止点击劫持。
|
||||
- 非 loopback 的 Control UI 部署必须显式设置 `gateway.controlUi.allowedOrigins`（完整 origin）。这也包括远程开发设置。
|
||||
- Gateway 网关 启动时可能会根据实际运行时绑定和端口预填充本地 origin，例如 `http://localhost:<port>` 和 `http://127.0.0.1:<port>`，但远程浏览器 origin 仍然需要显式条目。
|
||||
- Gateway 网关启动时可能会根据生效的运行时 bind 和端口，预填充诸如 `http://localhost:<port>` 和 `http://127.0.0.1:<port>` 之类的本地 origin，但远程浏览器 origin 仍需要显式条目。
|
||||
- 除非是在严格受控的本地测试中，否则不要使用 `gateway.controlUi.allowedOrigins: ["*"]`。它表示允许任意浏览器 origin，而不是“匹配我当前使用的任何主机”。
|
||||
- `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` 会启用 Host 请求头 origin 回退模式，但这是一种危险的安全模式。
|
||||
- `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` 会启用 Host 头 origin 回退模式，但这是一个危险的安全模式。
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
@ -424,11 +426,11 @@ Control UI 是静态文件；WebSocket 目标可配置，并且可以不同于 H
|
||||
}
|
||||
```
|
||||
|
||||
远程访问设置详情：[远程访问](/zh-CN/gateway/remote)。
|
||||
远程访问设置详情： [Remote access](/zh-CN/gateway/remote)。
|
||||
|
||||
## 相关
|
||||
## 相关内容
|
||||
|
||||
- [Dashboard](/zh-CN/web/dashboard) — gateway 仪表板
|
||||
- [健康检查](/zh-CN/gateway/health) — gateway 健康监控
|
||||
- [Dashboard](/zh-CN/web/dashboard) — Gateway 网关仪表板
|
||||
- [Health Checks](/zh-CN/gateway/health) — Gateway 网关健康监控
|
||||
- [TUI](/zh-CN/web/tui) — 终端用户界面
|
||||
- [WebChat](/zh-CN/web/webchat) — 基于浏览器的聊天界面
|
||||
|
||||
Loading…
Reference in New Issue
Block a user