chore(i18n): refresh zh-CN translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
8b99c8d838
commit
eabf6db73b
@ -1,48 +1,41 @@
|
||||
---
|
||||
read_when:
|
||||
- 你想在 API 提供商失败时使用可靠的回退方案
|
||||
- 当 API 提供商失效时，你希望有一个可靠的回退方案
|
||||
- 你正在运行 Codex CLI 或其他本地 AI CLI，并希望复用它们
|
||||
- 你想了解 CLI 后端工具访问的 MCP loopback 桥接机制
|
||||
summary: CLI 后端：带可选 MCP 工具桥接的本地 AI CLI 回退方案
|
||||
- 你想了解用于 CLI 后端工具访问的 MCP local loopback 桥接机制
|
||||
summary: CLI 后端：本地 AI CLI 回退，支持可选的 MCP 工具桥接
|
||||
title: CLI 后端
|
||||
x-i18n:
|
||||
generated_at: "2026-04-23T20:48:13Z"
|
||||
generated_at: "2026-04-23T21:49:31Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 86594b886c259df68591223e106c7507ab802321aaedebc9b243793c4f453388
|
||||
source_hash: d4f3f2f0a02539455de1a9f3982590e507e5ccd1e4cc354658118eadf522150a
|
||||
source_path: gateway/cli-backends.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# CLI 后端（回退运行时）
|
||||
|
||||
当 API 提供商不可用、
|
||||
受到速率限制或暂时异常时，OpenClaw 可以将**本地 AI CLI** 作为**纯文本回退方案**运行。这个机制刻意保持保守：
|
||||
当 API 提供商不可用、受到速率限制或暂时行为异常时，OpenClaw 可以运行**本地 AI CLI** 作为**纯文本回退**。这是一种有意保持保守的设计：
|
||||
|
||||
- **不会直接注入 OpenClaw 工具**，但带有 `bundleMcp: true`
|
||||
的后端可以通过 loopback MCP 桥接接收 Gateway 网关工具。
|
||||
- **支持 JSONL 流式传输**，适用于支持该能力的 CLI。
|
||||
- **支持会话**（因此后续轮次能保持连贯）。
|
||||
- **如果 CLI 接受图像路径**，则可以传递图像。
|
||||
- **不会直接注入 OpenClaw 工具**，但设置了 `bundleMcp: true` 的后端可以通过 loopback MCP 桥接接收 Gateway 网关工具。
|
||||
- 对支持该能力的 CLI 提供 **JSONL 流式传输**。
|
||||
- **支持会话**（因此后续轮次能够保持连贯）。
|
||||
- 如果 CLI 接受图片路径，**图片可以透传**。
|
||||
|
||||
这被设计为一种**安全网**，而不是主路径。当你
|
||||
希望在不依赖外部 API 的情况下获得“始终可用”的文本回复时，可以使用它。
|
||||
这被设计为一个**安全兜底机制**，而不是主要路径。当你希望在不依赖外部 API 的情况下获得“始终可用”的文本响应时，可以使用它。
|
||||
|
||||
如果你想要具有 ACP 会话控制、后台任务、
|
||||
线程 / 对话绑定以及持久化外部编码会话的完整 harness 运行时，请使用
|
||||
[ACP Agents](/zh-CN/tools/acp-agents)。CLI 后端不是 ACP。
|
||||
如果你想要一个具备 ACP 会话控制、后台任务、线程/会话绑定以及持久化外部编码会话的完整 harness 运行时，请改用 [ACP Agents](/zh-CN/tools/acp-agents)。CLI 后端不是 ACP。
|
||||
|
||||
## 面向初学者的快速开始
|
||||
|
||||
你可以**无需任何配置**使用 Codex CLI（内置 OpenAI 插件
|
||||
会注册一个默认后端）：
|
||||
你可以**无需任何配置**使用 Codex CLI（内置的 OpenAI 插件会注册一个默认后端）：
|
||||
|
||||
```bash
|
||||
openclaw agent --message "hi" --model codex-cli/gpt-5.5
|
||||
```
|
||||
|
||||
如果你的 Gateway 网关运行在 launchd / systemd 下，而 PATH 很精简，只需添加
|
||||
命令路径：
|
||||
如果你的 Gateway 网关运行在 launchd/systemd 下，且 `PATH` 很精简，只需添加命令路径：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -58,15 +51,13 @@ openclaw agent --message "hi" --model codex-cli/gpt-5.5
|
||||
}
|
||||
```
|
||||
|
||||
就这样。除了 CLI 本身之外，不需要额外的 key 或认证配置。
|
||||
就是这样。除了 CLI 自身所需的认证外，不需要密钥，也不需要额外的认证配置。
|
||||
|
||||
如果你在 Gateway 网关主机上将某个内置 CLI 后端用作**主消息提供商**，
|
||||
而你的配置又在模型引用或
|
||||
`agents.defaults.cliBackends` 下显式引用了该后端，那么 OpenClaw 现在会自动加载其所属的内置插件。
|
||||
如果你在 Gateway 网关主机上将内置的 CLI 后端用作**主要消息提供商**，当你的配置在模型引用或 `agents.defaults.cliBackends` 下显式引用该后端时，OpenClaw 现在会自动加载其所属的内置插件。
|
||||
|
||||
## 将其作为回退使用
|
||||
## 将其用作回退
|
||||
|
||||
将某个 CLI 后端添加到你的回退列表中，这样它只会在主模型失败时运行：
|
||||
将 CLI 后端加入你的回退列表，这样它只会在主要模型失败时运行：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -87,9 +78,8 @@ openclaw agent --message "hi" --model codex-cli/gpt-5.5
|
||||
|
||||
说明：
|
||||
|
||||
- 如果你使用 `agents.defaults.models`（允许列表），你也必须把 CLI 后端模型包含进去。
|
||||
- 如果主提供商失败（认证、速率限制、超时），OpenClaw 将
|
||||
接着尝试 CLI 后端。
|
||||
- 如果你使用 `agents.defaults.models`（允许列表），你也必须在其中包含 CLI 后端模型。
|
||||
- 如果主要提供商失败（认证、速率限制、超时），OpenClaw 会接着尝试 CLI 后端。
|
||||
|
||||
## 配置概览
|
||||
|
||||
@ -99,8 +89,8 @@ openclaw agent --message "hi" --model codex-cli/gpt-5.5
|
||||
agents.defaults.cliBackends
|
||||
```
|
||||
|
||||
每个条目都以一个**提供商 id** 为键（例如 `codex-cli`、`my-cli`）。
|
||||
这个提供商 id 会成为你的模型引用左半部分：
|
||||
每个条目都以**提供商 id** 为键（例如 `codex-cli`、`my-cli`）。
|
||||
该提供商 id 会成为模型引用左侧部分：
|
||||
|
||||
```
|
||||
<provider>/<model>
|
||||
@ -130,7 +120,7 @@ agents.defaults.cliBackends
|
||||
sessionMode: "existing",
|
||||
sessionIdFields: ["session_id", "conversation_id"],
|
||||
systemPromptArg: "--system",
|
||||
// Codex 风格 CLI 可以改为指向提示词文件：
|
||||
// Codex 风格的 CLI 也可以改为指向一个提示文件：
|
||||
// systemPromptFileConfigArg: "-c",
|
||||
// systemPromptFileConfigKey: "model_instructions_file",
|
||||
systemPromptWhen: "first",
|
||||
@ -146,33 +136,25 @@ agents.defaults.cliBackends
|
||||
|
||||
## 工作原理
|
||||
|
||||
1. **根据提供商前缀选择后端**（`codex-cli/...`）。
|
||||
2. **使用相同的 OpenClaw 提示词 + 工作区上下文构建系统提示词**。
|
||||
3. **使用会话 id 执行 CLI**（如果支持），以保持历史一致。
|
||||
内置的 `claude-cli` 后端会为每个
|
||||
OpenClaw 会话保持一个 Claude stdio 进程存活，并通过 stream-json stdin 发送后续轮次。
|
||||
1. 根据提供商前缀（`codex-cli/...`）**选择后端**。
|
||||
2. 使用相同的 OpenClaw 提示词和工作区上下文**构建系统提示词**。
|
||||
3. 使用会话 id（如果支持）**执行 CLI**，以保持历史一致。
|
||||
内置的 `claude-cli` 后端会为每个 OpenClaw 会话保持一个 Claude stdio 进程存活，
|
||||
并通过 stream-json stdin 发送后续轮次。
|
||||
4. **解析输出**（JSON 或纯文本），并返回最终文本。
|
||||
5. **按后端持久化会话 id**，这样后续轮次会复用相同的 CLI 会话。
|
||||
5. 按后端**持久化会话 id**，以便后续轮次复用同一个 CLI 会话。
|
||||
|
||||
<Note>
|
||||
内置 Anthropic `claude-cli` 后端现已重新受支持。Anthropic 工作人员
|
||||
告诉我们，OpenClaw 风格的 Claude CLI 用法再次被允许，因此 OpenClaw 将
|
||||
`claude -p` 用法视为此集成的许可用法，除非 Anthropic 发布
|
||||
新的政策。
|
||||
内置的 Anthropic `claude-cli` 后端现已再次受支持。Anthropic 员工告诉我们，允许使用 OpenClaw 风格的 Claude CLI，因此除非 Anthropic 发布新的策略，否则 OpenClaw 会将这种集成中的 `claude -p` 用法视为被认可的方式。
|
||||
</Note>
|
||||
|
||||
内置 OpenAI `codex-cli` 后端会通过
|
||||
Codex 的 `model_instructions_file` 配置覆盖项（`-c
|
||||
model_instructions_file="..."`）传递 OpenClaw 的系统提示词。Codex 不提供类似 Claude 风格的
|
||||
`--append-system-prompt` 标志，因此 OpenClaw 会为每个新的 Codex CLI 会话
|
||||
将组装后的提示词写入一个临时文件。
|
||||
内置的 OpenAI `codex-cli` 后端通过 Codex 的 `model_instructions_file` 配置覆盖项（`-c
|
||||
model_instructions_file="..."`）传递 OpenClaw 的系统提示词。Codex 不提供类似 Claude 的
|
||||
`--append-system-prompt` 标志，因此 OpenClaw 会为每个新的 Codex CLI 会话将组装好的提示词写入一个临时文件。
|
||||
|
||||
内置 Anthropic `claude-cli` 后端会通过
|
||||
两种方式接收 OpenClaw 的 Skills 快照：一种是附加系统提示词中的紧凑 OpenClaw Skills 目录，另一种是
|
||||
通过 `--plugin-dir` 传入的临时 Claude Code 插件。该插件仅包含对该智能体 / 会话适用的 Skills，
|
||||
因此 Claude Code 原生 Skills 解析器看到的就是与 OpenClaw 在提示词中会公布的同一套经过筛选的内容。Skill 环境变量 / API key 覆盖仍由 OpenClaw 应用于该次运行的子进程环境。
|
||||
内置的 Anthropic `claude-cli` 后端会通过两种方式接收 OpenClaw 的 Skills 快照：一种是附加系统提示词中的精简版 OpenClaw Skills 目录，另一种是通过 `--plugin-dir` 传入的临时 Claude Code 插件。该插件仅包含对该智能体/会话可用的 Skills，因此 Claude Code 的原生 skill 解析器看到的过滤后集合，与 OpenClaw 原本会在提示词中声明的集合相同。针对 Skill 的环境变量/API 密钥覆盖仍然会由 OpenClaw 应用到本次运行的子进程环境中。
|
||||
|
||||
在 OpenClaw 可以使用内置 `claude-cli` 后端之前，Claude Code 本身必须已经在同一台主机上登录：
|
||||
在 OpenClaw 可以使用内置的 `claude-cli` 后端之前，Claude Code 本身必须已经在同一台主机上登录：
|
||||
|
||||
```bash
|
||||
claude auth login
|
||||
@ -180,75 +162,56 @@ claude auth status --text
|
||||
openclaw models auth login --provider anthropic --method cli --set-default
|
||||
```
|
||||
|
||||
仅当 `claude`
|
||||
二进制文件尚未存在于 `PATH` 中时，才使用 `agents.defaults.cliBackends.claude-cli.command`。
|
||||
只有当 `claude` 二进制文件不在 `PATH` 中时，才需要使用 `agents.defaults.cliBackends.claude-cli.command`。
|
||||
|
||||
## 会话
|
||||
|
||||
- 如果 CLI 支持会话，请设置 `sessionArg`（例如 `--session-id`）或
|
||||
`sessionArgs`（占位符 `{sessionId}`），当需要将 ID 插入
|
||||
到多个标志中时使用。
|
||||
- 如果 CLI 使用带有不同标志的**resume 子命令**，请设置
|
||||
`resumeArgs`（恢复时替代 `args`），并可选设置
|
||||
`resumeOutput`（用于非 JSON 恢复）。
|
||||
`sessionArgs`（占位符 `{sessionId}`），用于需要将 id 插入多个标志的情况。
|
||||
- 如果 CLI 使用带有不同标志的**恢复子命令**，请设置
|
||||
`resumeArgs`（恢复时替换 `args`），并可选设置 `resumeOutput`
|
||||
（用于非 JSON 的恢复）。
|
||||
- `sessionMode`：
|
||||
- `always`：总是发送会话 id（如果未存储，则生成新的 UUID）。
|
||||
- `existing`：仅在之前已存储会话 id 时发送。
|
||||
- `none`：永不发送会话 id。
|
||||
- `always`：始终发送会话 id（如果未存储则生成新的 UUID）。
|
||||
- `existing`：仅在之前已存储时发送会话 id。
|
||||
- `none`：从不发送会话 id。
|
||||
- `claude-cli` 默认使用 `liveSession: "claude-stdio"`、`output: "jsonl"`、
|
||||
和 `input: "stdin"`，因此后续轮次会在 Claude 进程仍处于活动状态时复用该活动 Claude 进程。
|
||||
现在 warm stdio 是默认行为，包括那些省略传输字段的自定义配置
|
||||
也是如此。如果 Gateway 网关重启，或者空闲进程
|
||||
退出，OpenClaw 会从已存储的 Claude 会话 id 恢复。已存储的会话
|
||||
id 会先与现有可读的项目转录进行校验，再执行
|
||||
恢复，因此虚假的绑定会以 `reason=transcript-missing`
|
||||
被清除，而不是在 `--resume` 下静默启动新的 Claude CLI 会话。
|
||||
- 已存储的 CLI 会话属于提供商拥有的连续性。隐式的每日会话
|
||||
重置不会中断它们；`/reset` 和显式 `session.reset` 策略
|
||||
才会。
|
||||
和 `input: "stdin"`，这样在 Claude 进程仍处于活动状态时，后续轮次就能复用该实时 Claude 进程。现在默认就是预热的 stdio，包括那些省略传输字段的自定义配置。如果 Gateway 网关重启，或者空闲进程退出，OpenClaw 会从已存储的 Claude 会话 id 恢复。已存储的会话 id 会先针对现有且可读的项目转录进行校验，再执行恢复，因此虚假的绑定会以 `reason=transcript-missing` 被清除，而不是在 `--resume` 下悄悄启动一个全新的 Claude CLI 会话。
|
||||
- 已存储的 CLI 会话属于提供商自身的连续性状态。隐式的每日会话重置不会切断它们；`/reset` 和显式的 `session.reset` 策略仍然会切断。
|
||||
|
||||
序列化说明：
|
||||
|
||||
- `serialize: true` 会保持同一通道中的运行按顺序执行。
|
||||
- 大多数 CLI 都会在一个提供商通道上串行化。
|
||||
- 当所选认证身份发生变化时，OpenClaw 会放弃复用已存储的 CLI 会话，
|
||||
包括 auth profile id 变化、静态 API key 变化、静态 token 变化，或
|
||||
当 CLI 暴露该信息时 OAuth 账户身份变化。
|
||||
OAuth access token 和 refresh token 的轮换不会中断已存储的 CLI 会话。
|
||||
如果某个 CLI 不暴露稳定的 OAuth 账户 id，OpenClaw 会让该 CLI 自行强制执行恢复权限。
|
||||
- `serialize: true` 会保持同一执行通道中的运行顺序。
|
||||
- 大多数 CLI 会在一个提供商通道上串行执行。
|
||||
- 当所选认证身份发生变化时，OpenClaw 会放弃复用已存储的 CLI 会话，包括认证配置文件 id、静态 API 密钥、静态令牌，或 CLI 暴露该信息时的 OAuth 账户身份发生变化。OAuth 访问令牌和刷新令牌轮换不会切断已存储的 CLI 会话。如果某个 CLI 没有暴露稳定的 OAuth 账户 id，OpenClaw 会让该 CLI 自行强制执行恢复权限。
|
||||
|
||||
## 图像（透传）
|
||||
## 图片（透传）
|
||||
|
||||
如果你的 CLI 接受图像路径，请设置 `imageArg`：
|
||||
如果你的 CLI 接受图片路径，请设置 `imageArg`：
|
||||
|
||||
```json5
|
||||
imageArg: "--image",
|
||||
imageMode: "repeat"
|
||||
```
|
||||
|
||||
OpenClaw 会将 base64 图像写入临时文件。如果设置了 `imageArg`，
|
||||
这些路径就会作为 CLI 参数传入。如果缺少 `imageArg`，OpenClaw 会将
|
||||
文件路径追加到提示词中（路径注入），这足以满足那些会从普通路径自动
|
||||
加载本地文件的 CLI。
|
||||
OpenClaw 会将 base64 图片写入临时文件。如果设置了 `imageArg`，这些路径会作为 CLI 参数传入。如果缺少 `imageArg`，OpenClaw 会将文件路径附加到提示词中（路径注入），这对于那些能从普通路径自动加载本地文件的 CLI 已经足够。
|
||||
|
||||
## 输入 / 输出
|
||||
|
||||
- `output: "json"`（默认）会尝试解析 JSON，并提取文本 + 会话 id。
|
||||
- 对于 Gemini CLI JSON 输出，当 `usage` 缺失或为空时，OpenClaw 会从 `response` 读取回复文本，
|
||||
并从 `stats` 读取用量。
|
||||
- `output: "jsonl"` 会解析 JSONL 流（例如 Codex CLI `--json`），并提取最终智能体消息以及会话
|
||||
标识符（如果存在）。
|
||||
- `output: "json"`（默认）会尝试解析 JSON 并提取文本和会话 id。
|
||||
- 对于 Gemini CLI 的 JSON 输出，当 `usage` 缺失或为空时，OpenClaw 会从 `response` 读取回复文本，并从 `stats` 读取用量。
|
||||
- `output: "jsonl"` 会解析 JSONL 流（例如 Codex CLI `--json`），并提取最终的智能体消息以及存在时的会话标识符。
|
||||
- `output: "text"` 将 stdout 视为最终响应。
|
||||
|
||||
输入模式：
|
||||
|
||||
- `input: "arg"`（默认）将提示词作为最后一个 CLI 参数传递。
|
||||
- `input: "stdin"` 通过 stdin 发送提示词。
|
||||
- 如果提示词很长并设置了 `maxPromptArgChars`，则会改用 stdin。
|
||||
- 如果提示词很长并且设置了 `maxPromptArgChars`，则会使用 stdin。
|
||||
|
||||
## 默认值（由插件持有）
|
||||
## 默认值（插件拥有）
|
||||
|
||||
内置 OpenAI 插件还会为 `codex-cli` 注册一个默认值：
|
||||
内置的 OpenAI 插件也会为 `codex-cli` 注册一个默认值：
|
||||
|
||||
- `command: "codex"`
|
||||
- `args: ["exec","--json","--color","never","--sandbox","workspace-write","--skip-git-repo-check"]`
|
||||
@ -259,7 +222,7 @@ OpenClaw 会将 base64 图像写入临时文件。如果设置了 `imageArg`，
|
||||
- `imageArg: "--image"`
|
||||
- `sessionMode: "existing"`
|
||||
|
||||
内置 Google 插件也会为 `google-gemini-cli` 注册一个默认值：
|
||||
内置的 Google 插件也会为 `google-gemini-cli` 注册一个默认值：
|
||||
|
||||
- `command: "gemini"`
|
||||
- `args: ["--output-format", "json", "--prompt", "{prompt}"]`
|
||||
@ -270,31 +233,31 @@ OpenClaw 会将 base64 图像写入临时文件。如果设置了 `imageArg`，
|
||||
- `sessionMode: "existing"`
|
||||
- `sessionIdFields: ["session_id", "sessionId"]`
|
||||
|
||||
前提条件：本地 Gemini CLI 必须已安装，并且可以通过
|
||||
`PATH` 中的 `gemini` 访问（`brew install gemini-cli` 或
|
||||
前提条件：本地 Gemini CLI 必须已安装，并且可以通过 `PATH` 中的
|
||||
`gemini` 调用（`brew install gemini-cli` 或
|
||||
`npm install -g @google/gemini-cli`）。
|
||||
|
||||
Gemini CLI JSON 说明：
|
||||
|
||||
- 回复文本从 JSON `response` 字段读取。
|
||||
- 当 `usage` 不存在或为空时，用量回退到 `stats`。
|
||||
- `stats.cached` 会被标准化为 OpenClaw 的 `cacheRead`。
|
||||
- 如果 `stats.input` 缺失，OpenClaw 会根据
|
||||
- 回复文本从 JSON 的 `response` 字段读取。
|
||||
- 当 `usage` 不存在或为空时，用量会回退到 `stats`。
|
||||
- `stats.cached` 会被标准化为 OpenClaw `cacheRead`。
|
||||
- 如果缺少 `stats.input`，OpenClaw 会根据
|
||||
`stats.input_tokens - stats.cached` 推导输入 token 数。
|
||||
|
||||
仅在需要时覆盖（常见情况：绝对 `command` 路径）。
|
||||
仅在需要时覆盖（常见情况：使用绝对 `command` 路径）。
|
||||
|
||||
## 由插件持有的默认值
|
||||
## 插件拥有的默认值
|
||||
|
||||
CLI 后端默认值现在属于插件表面的一部分：
|
||||
|
||||
- 插件通过 `api.registerCliBackend(...)` 注册它们。
|
||||
- 后端 `id` 会成为模型引用中的提供商前缀。
|
||||
- 用户在 `agents.defaults.cliBackends.<id>` 中的配置仍会覆盖插件默认值。
|
||||
- 后端特定的配置清理由插件通过可选
|
||||
`normalizeConfig` hook 持有。
|
||||
- 位于 `agents.defaults.cliBackends.<id>` 下的用户配置仍会覆盖插件默认值。
|
||||
- 特定后端的配置清理仍通过可选的
|
||||
`normalizeConfig` hook 由插件负责。
|
||||
|
||||
需要进行微小提示词 / 消息兼容性调整的插件，可以声明双向文本转换，而无需替换提供商或 CLI 后端：
|
||||
如果插件需要细微的提示词/消息兼容性 shim，可以声明双向文本转换，而无需替换提供商或 CLI 后端：
|
||||
|
||||
```typescript
|
||||
api.registerTextTransforms({
|
||||
@ -312,50 +275,50 @@ api.registerTextTransforms({
|
||||
```
|
||||
|
||||
`input` 会重写传递给 CLI 的系统提示词和用户提示词。`output`
|
||||
会在 OpenClaw 处理其自身控制标记和渠道投递之前，重写流式助手增量和解析后的最终文本。
|
||||
会在 OpenClaw 处理其自身控制标记和渠道投递之前，重写流式传输的 assistant 增量内容以及解析后的最终文本。
|
||||
|
||||
对于输出 Claude Code stream-json 兼容 JSONL 的 CLI，
|
||||
请在该后端配置中设置
|
||||
对于输出与 Claude Code stream-json 兼容的 JSONL 的 CLI，请在该后端配置中设置
|
||||
`jsonlDialect: "claude-stream-json"`。
|
||||
|
||||
## Bundle MCP 覆盖层
|
||||
|
||||
CLI 后端**不会**直接接收 OpenClaw 工具调用，但某个后端可以
|
||||
通过 `bundleMcp: true` 选择启用自动生成的 MCP 配置覆盖层。
|
||||
CLI 后端**不会**直接接收 OpenClaw 工具调用，但后端可以通过设置
|
||||
`bundleMcp: true` 选择加入一个生成的 MCP 配置覆盖层。
|
||||
|
||||
当前内置行为：
|
||||
当前的内置行为：
|
||||
|
||||
- `claude-cli`：自动生成严格 MCP 配置文件
|
||||
- `codex-cli`：`mcp_servers` 的内联配置覆盖
|
||||
- `google-gemini-cli`：自动生成 Gemini 系统设置文件
|
||||
- `claude-cli`：生成严格的 MCP 配置文件
|
||||
- `codex-cli`：为 `mcp_servers` 生成内联配置覆盖；生成的
|
||||
OpenClaw loopback 服务器会标记为 Codex 的每服务器工具批准模式，
|
||||
这样 MCP 调用就不会因为本地批准提示而卡住
|
||||
- `google-gemini-cli`：生成 Gemini system settings 文件
|
||||
|
||||
启用 bundle MCP 时，OpenClaw 会：
|
||||
启用 bundle MCP 时，OpenClaw：
|
||||
|
||||
- 启动一个 loopback HTTP MCP 服务器，将 Gateway 网关工具暴露给 CLI 进程
|
||||
- 使用按会话生成的令牌（`OPENCLAW_MCP_TOKEN`）对桥接进行身份验证
|
||||
- 将工具访问范围限制在当前会话、账户和渠道上下文中
|
||||
- 启动一个 loopback HTTP MCP 服务器，向 CLI 进程暴露 Gateway 网关工具
|
||||
- 使用每会话令牌（`OPENCLAW_MCP_TOKEN`）对桥接进行认证
|
||||
- 将工具访问范围限制在当前会话、账户和渠道上下文内
|
||||
- 为当前工作区加载已启用的 bundle-MCP 服务器
|
||||
- 将它们与任何现有的后端 MCP 配置 / 设置结构合并
|
||||
- 使用所属扩展定义的后端集成模式重写启动配置
|
||||
- 将它们与任何现有的后端 MCP 配置/设置结构合并
|
||||
- 使用所属扩展中由后端拥有的集成模式重写启动配置
|
||||
|
||||
如果没有启用任何 MCP 服务器，只要某个
|
||||
后端选择启用 bundle MCP，OpenClaw 仍会注入严格配置，以便后台运行保持隔离。
|
||||
如果没有启用任何 MCP 服务器，当后端选择加入 bundle MCP 时，OpenClaw 仍会注入严格配置，以便后台运行保持隔离。
|
||||
|
||||
## 限制
|
||||
|
||||
- **没有直接的 OpenClaw 工具调用。** OpenClaw 不会将工具调用直接注入
|
||||
到 CLI 后端协议中。后端只有在选择启用
|
||||
`bundleMcp: true` 时，才会看到 Gateway 网关工具。
|
||||
- **流式传输取决于后端。** 有些后端会流式输出 JSONL；其他后端则会缓冲
|
||||
- **没有直接的 OpenClaw 工具调用。** OpenClaw 不会将工具调用注入到
|
||||
CLI 后端协议中。只有当后端选择加入
|
||||
`bundleMcp: true` 时，后端才会看到 Gateway 网关工具。
|
||||
- **流式传输是后端特定的。** 一些后端流式传输 JSONL；另一些则会缓冲
|
||||
直到退出。
|
||||
- **结构化输出**取决于 CLI 的 JSON 格式。
|
||||
- **Codex CLI 会话**通过文本输出恢复（没有 JSONL），因此其结构化程度
|
||||
不如初始的 `--json` 运行。不过 OpenClaw 会话本身仍可正常工作。
|
||||
- **结构化输出** 取决于 CLI 的 JSON 格式。
|
||||
- **Codex CLI 会话** 通过文本输出恢复（没有 JSONL），其结构化程度
|
||||
低于初始的 `--json` 运行。不过 OpenClaw 会话本身仍可正常工作。
|
||||
|
||||
## 故障排除
|
||||
|
||||
- **找不到 CLI：** 请将 `command` 设置为完整路径。
|
||||
- **模型名称错误：** 使用 `modelAliases` 将 `provider/model` 映射到 CLI 模型。
|
||||
- **没有会话连续性：** 请确保已设置 `sessionArg`，且 `sessionMode` 不是
|
||||
`none`（Codex CLI 当前无法通过 JSON 输出恢复）。
|
||||
- **图像被忽略：** 请设置 `imageArg`（并确认 CLI 支持文件路径）。
|
||||
- **找不到 CLI**：将 `command` 设置为完整路径。
|
||||
- **模型名称错误**：使用 `modelAliases` 将 `provider/model` 映射到 CLI 模型。
|
||||
- **没有会话连续性**：确保已设置 `sessionArg`，且 `sessionMode` 不为
|
||||
`none`（Codex CLI 当前无法使用 JSON 输出恢复）。
|
||||
- **图片被忽略**：设置 `imageArg`（并确认 CLI 支持文件路径）。
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@ -1,30 +1,24 @@
|
||||
---
|
||||
read_when:
|
||||
- 你想使用内置的 Codex app-server harness
|
||||
- 你想使用内置的 Codex 应用服务器测试框架
|
||||
- 你需要 Codex 模型引用和配置示例
|
||||
- 你想为仅 Codex 部署禁用 PI 回退 സംവിധ to=final code omitted
|
||||
summary: 通过内置的 Codex app-server harness 运行 OpenClaw 嵌入式智能体轮次
|
||||
title: Codex harness
|
||||
- 你想为仅使用 Codex 的部署禁用 Pi 回退机制
|
||||
summary: 通过内置的 Codex 应用服务器测试框架运行 OpenClaw 嵌入式智能体回合
|
||||
title: Codex 测试框架
|
||||
x-i18n:
|
||||
generated_at: "2026-04-23T20:56:54Z"
|
||||
generated_at: "2026-04-23T21:49:32Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 65e96ac709a7996878037da3ffb8903cdd3ad83bb5de75c47ab2f0a08882098c
|
||||
source_hash: 27b7b662c5eb2002fed8d2c752c4227a46a89d767ac838138327e64df84e4919
|
||||
source_path: plugins/codex-harness.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
内置的 `codex` 插件让 OpenClaw 可以通过
|
||||
Codex app-server，而不是内置的 PI harness，来运行嵌入式智能体轮次。
|
||||
内置的 `codex` 插件让 OpenClaw 可以通过 Codex 应用服务器运行嵌入式智能体回合，而不是使用内置的 Pi 测试框架。
|
||||
|
||||
当你希望由 Codex 接管底层智能体会话时，请使用它：模型
|
||||
发现、原生线程恢复、原生压缩总结，以及 app-server 执行。
|
||||
OpenClaw 仍然负责聊天渠道、会话文件、模型选择、工具、
|
||||
审批、媒体传递，以及可见的转录镜像。
|
||||
当你希望由 Codex 接管底层智能体会话时，请使用此功能：模型发现、原生线程恢复、原生压缩，以及应用服务器执行。OpenClaw 仍然负责聊天渠道、会话文件、模型选择、工具、审批、媒体传输，以及可见的转录镜像。
|
||||
|
||||
原生 Codex 轮次同样遵循共享插件 hooks，因此提示词 shim、
|
||||
感知压缩总结的自动化、工具中间件以及生命周期观察器都能与
|
||||
PI harness 保持一致：
|
||||
原生 Codex 回合同样会遵循共享的插件钩子，因此提示词 shim、压缩感知自动化、工具中间件和生命周期观察器都能与 Pi 测试框架保持一致：
|
||||
|
||||
- `before_prompt_build`
|
||||
- `before_compaction`, `after_compaction`
|
||||
@ -33,57 +27,42 @@ PI harness 保持一致：
|
||||
- `before_message_write`
|
||||
- `agent_end`
|
||||
|
||||
内置插件还可以注册 Codex app-server extension factory，以添加
|
||||
异步 `tool_result` 中间件。
|
||||
内置插件还可以注册一个 Codex 应用服务器扩展工厂，以添加异步 `tool_result` 中间件。
|
||||
|
||||
该 harness 默认关闭。新配置应保持 OpenAI 模型引用
|
||||
规范为 `openai/gpt-*`，并在需要原生 app-server 执行时显式强制设置
|
||||
`embeddedHarness.runtime: "codex"` 或 `OPENCLAW_AGENT_RUNTIME=codex`。
|
||||
旧版 `codex/*` 模型引用仍会为兼容性自动选择该 harness。
|
||||
该测试框架默认关闭。新配置应将 OpenAI 模型引用规范地保持为 `openai/gpt-*`，并在希望使用原生应用服务器执行时，显式强制设置 `embeddedHarness.runtime: "codex"` 或 `OPENCLAW_AGENT_RUNTIME=codex`。为了兼容性，旧版 `codex/*` 模型引用仍会自动选择该测试框架。
|
||||
|
||||
## 选择正确的模型前缀
|
||||
|
||||
OpenClaw 现在会将 OpenAI GPT 模型引用统一规范为 `openai/*`：
|
||||
OpenClaw 现在将 OpenAI GPT 模型引用统一规范为 `openai/*`：
|
||||
|
||||
| 模型引用 | 运行时路径 | 适用场景 |
|
||||
| 模型引用 | 运行时路径 | 使用场景 |
|
||||
| ----------------------------------------------------- | -------------------------------------------- | ----------------------------------------------------------------------- |
|
||||
| `openai/gpt-5.5` | 通过 OpenClaw/PI 流程访问 OpenAI 提供商 | 你希望使用 `OPENAI_API_KEY` 直接访问 OpenAI Platform API。 |
|
||||
| `openai/gpt-5.5` + `embeddedHarness.runtime: "codex"` | Codex app-server harness | 你希望对嵌入式智能体轮次使用原生 Codex app-server 执行。 |
|
||||
| `openai/gpt-5.5` | 通过 OpenClaw/Pi 管线的 OpenAI 提供商 | 你希望使用 `OPENAI_API_KEY` 直接访问 OpenAI Platform API。 |
|
||||
| `openai/gpt-5.5` + `embeddedHarness.runtime: "codex"` | Codex 应用服务器测试框架 | 你希望嵌入式智能体回合使用原生 Codex 应用服务器执行。 |
|
||||
|
||||
旧版 `openai-codex/gpt-*` 和 `codex/gpt-*` 引用仍然接受作为
|
||||
兼容性别名，但新的文档/配置示例应使用 `openai/gpt-*`。
|
||||
旧版 `openai-codex/gpt-*` 和 `codex/gpt-*` 引用仍然作为兼容别名被接受，但新的文档和配置示例应使用 `openai/gpt-*`。
|
||||
|
||||
Harness 选择不是一个实时会话控制项。当一个嵌入式轮次运行时，
|
||||
OpenClaw 会在该会话上记录所选 harness id，并继续在同一会话 id 的后续轮次中使用它。若你希望未来会话改用其他 harness，请更改 `embeddedHarness` 配置或
|
||||
`OPENCLAW_AGENT_RUNTIME`；在已有会话于 PI 和 Codex 之间切换之前，
|
||||
请使用 `/new` 或 `/reset` 启动一个全新会话。这可以避免将同一份转录
|
||||
重放到两个彼此不兼容的原生会话系统中。
|
||||
使用 `/status` 确认当前会话实际使用的测试框架。如果选择结果令人意外，请为 `agents/harness` 子系统启用调试日志，并检查 Gateway 网关中的结构化 `agent harness selected` 记录。它包含所选测试框架 id、选择原因、运行时/回退策略，以及在 `auto` 模式下每个插件候选项的支持结果。
|
||||
|
||||
在引入 harness pin 之前创建的旧会话，一旦拥有转录历史，就会被视为
|
||||
固定到 PI。更改配置后，请使用 `/new` 或 `/reset`，将该会话显式切换到
|
||||
Codex。
|
||||
测试框架选择不是实时会话控制。当嵌入式回合运行时，OpenClaw 会将选中的测试框架 id 记录到该会话上，并在同一会话 id 的后续回合中继续使用它。当你希望未来的新会话使用另一种测试框架时，请更改 `embeddedHarness` 配置或 `OPENCLAW_AGENT_RUNTIME`；如果要在现有对话中在 Pi 和 Codex 之间切换，请先使用 `/new` 或 `/reset` 启动一个新会话。这样可以避免用两套不兼容的原生会话系统重放同一份转录记录。
|
||||
|
||||
`/status` 会在 `Fast` 旁显示生效的非 PI harness，例如
|
||||
`Fast · codex`。默认的 PI harness 仍显示为 `Runner: pi (embedded)`，并且不会
|
||||
额外显示单独的 harness 徽章。
|
||||
在引入测试框架固定机制之前创建的旧会话，一旦已有转录历史，就会被视为固定到 Pi。更改配置后，请使用 `/new` 或 `/reset`，让该对话改为使用 Codex。
|
||||
|
||||
`/status` 会在 `Fast` 旁边显示当前实际使用的非 Pi 测试框架，例如 `Fast · codex`。默认的 Pi 测试框架仍显示为 `Runner: pi (embedded)`，不会额外显示单独的测试框架徽标。
|
||||
|
||||
## 要求
|
||||
|
||||
- OpenClaw，且内置 `codex` 插件可用。
|
||||
- Codex app-server `0.118.0` 或更高版本。
|
||||
- app-server 进程可使用的 Codex 认证。
|
||||
- OpenClaw，且可用内置的 `codex` 插件。
|
||||
- Codex 应用服务器 `0.118.0` 或更高版本。
|
||||
- 应用服务器进程可用的 Codex 认证信息。
|
||||
|
||||
该插件会阻止旧版或未带版本号的 app-server 握手。这可以确保
|
||||
OpenClaw 只运行在已测试过的协议表面上。
|
||||
该插件会阻止较旧或没有版本信息的应用服务器握手。这可确保 OpenClaw 始终使用其已测试过的协议接口。
|
||||
|
||||
对于 live 和 Docker smoke 测试，认证通常来自 `OPENAI_API_KEY`，以及
|
||||
可选的 Codex CLI 文件，例如 `~/.codex/auth.json` 和
|
||||
`~/.codex/config.toml`。请使用与你本地 Codex app-server
|
||||
相同的认证材料。
|
||||
对于实时和 Docker 冒烟测试，认证信息通常来自 `OPENAI_API_KEY`，以及可选的 Codex CLI 文件，如 `~/.codex/auth.json` 和 `~/.codex/config.toml`。请使用与你本地 Codex 应用服务器相同的认证材料。
|
||||
|
||||
## 最小配置
|
||||
|
||||
使用 `openai/gpt-5.5`，启用内置插件，并强制使用 `codex` harness：
|
||||
使用 `openai/gpt-5.5`，启用内置插件，并强制使用 `codex` 测试框架：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -106,7 +85,7 @@ OpenClaw 只运行在已测试过的协议表面上。
|
||||
}
|
||||
```
|
||||
|
||||
如果你的配置使用 `plugins.allow`，也请将 `codex` 包含进去：
|
||||
如果你的配置使用了 `plugins.allow`，也请将 `codex` 包含进去：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -121,14 +100,11 @@ OpenClaw 只运行在已测试过的协议表面上。
|
||||
}
|
||||
```
|
||||
|
||||
旧配置如果将 `agents.defaults.model` 或某个智能体模型设置为
|
||||
`codex/<model>`，仍会自动启用内置 `codex` 插件。新配置应优先使用
|
||||
`openai/<model>`，并搭配上面的显式 `embeddedHarness` 条目。
|
||||
如果旧版配置将 `agents.defaults.model` 或某个智能体模型设置为 `codex/<model>`，仍会自动启用内置的 `codex` 插件。新配置应优先使用 `openai/<model>`，并配合上面显式的 `embeddedHarness` 配置项。
|
||||
|
||||
## 添加 Codex 而不替换其他模型
|
||||
## 在不替换其他模型的情况下添加 Codex
|
||||
|
||||
当你希望旧版 `codex/*` 引用选择 Codex，而其他所有情况仍使用
|
||||
PI 时，请保持 `runtime: "auto"`。对于新配置，建议在需要使用该 harness 的智能体上显式设置 `runtime: "codex"`。
|
||||
如果你希望旧版 `codex/*` 引用选择 Codex，而其他所有内容继续使用 Pi，请保持 `runtime: "auto"`。对于新配置，建议仅在应使用该测试框架的智能体上显式设置 `runtime: "codex"`。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -158,16 +134,15 @@ PI 时，请保持 `runtime: "auto"`。对于新配置，建议在需要使用
|
||||
}
|
||||
```
|
||||
|
||||
采用这种形状时：
|
||||
在这种结构下：
|
||||
|
||||
- `/model gpt` 或 `/model openai/gpt-5.5` 会为该配置使用 Codex app-server harness。
|
||||
- `/model opus` 会使用 Anthropic 提供商路径。
|
||||
- 如果选择了非 Codex 模型，PI 仍然作为兼容性 harness 保留。
|
||||
- `/model gpt` 或 `/model openai/gpt-5.5` 会在此配置中使用 Codex 应用服务器测试框架。
|
||||
- `/model opus` 使用 Anthropic 提供商路径。
|
||||
- 如果选择的是非 Codex 模型，Pi 仍然是兼容性测试框架。
|
||||
|
||||
## 仅 Codex 部署
|
||||
## 仅使用 Codex 的部署
|
||||
|
||||
当你需要证明每一个嵌入式智能体轮次都使用
|
||||
Codex harness 时，请禁用 PI 回退：
|
||||
当你需要证明每一个嵌入式智能体回合都使用 Codex 测试框架时，请禁用 Pi 回退：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -183,7 +158,7 @@ Codex harness 时，请禁用 PI 回退：
|
||||
}
|
||||
```
|
||||
|
||||
环境变量覆盖：
|
||||
环境覆盖：
|
||||
|
||||
```bash
|
||||
OPENCLAW_AGENT_RUNTIME=codex \
|
||||
@ -191,13 +166,11 @@ OPENCLAW_AGENT_HARNESS_FALLBACK=none \
|
||||
openclaw gateway run
|
||||
```
|
||||
|
||||
禁用回退后，如果 Codex 插件被禁用、
|
||||
app-server 版本过旧，或 app-server 无法启动，OpenClaw 会快速失败。
|
||||
禁用回退后，如果 Codex 插件被禁用、应用服务器版本过旧，或者应用服务器无法启动，OpenClaw 会尽早失败。
|
||||
|
||||
## 按智能体使用 Codex
|
||||
## 按智能体启用 Codex
|
||||
|
||||
你可以让某个智能体仅使用 Codex，而默认智能体保持正常的
|
||||
自动选择：
|
||||
你可以让某个智能体仅使用 Codex，而默认智能体保持普通的自动选择：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -228,15 +201,11 @@ app-server 版本过旧，或 app-server 无法启动，OpenClaw 会快速失败
|
||||
}
|
||||
```
|
||||
|
||||
使用常规会话命令切换智能体和模型。`/new` 会创建一个全新的
|
||||
OpenClaw 会话，而 Codex harness 会按需创建或恢复其侧车 app-server
|
||||
线程。`/reset` 会清除该线程的 OpenClaw 会话绑定，
|
||||
并让下一轮再次根据当前配置解析 harness。
|
||||
使用常规会话命令切换智能体和模型。`/new` 会创建一个新的 OpenClaw 会话，而 Codex 测试框架会按需创建或恢复它的 sidecar 应用服务器线程。`/reset` 会清除该线程的 OpenClaw 会话绑定，并让下一回合重新根据当前配置解析测试框架。
|
||||
|
||||
## 模型发现
|
||||
|
||||
默认情况下，Codex 插件会向 app-server 请求可用模型。如果
|
||||
发现失败或超时，它会使用内置的回退目录，其中包括：
|
||||
默认情况下，Codex 插件会向应用服务器请求可用模型。如果发现失败或超时，它会使用内置的回退目录，包含：
|
||||
|
||||
- GPT-5.5
|
||||
- GPT-5.4 mini
|
||||
@ -262,8 +231,7 @@ OpenClaw 会话，而 Codex harness 会按需创建或恢复其侧车 app-server
|
||||
}
|
||||
```
|
||||
|
||||
如果你希望启动时避免探测 Codex，并固定使用回退目录，
|
||||
请禁用发现：
|
||||
如果你希望启动时避免探测 Codex，并始终使用回退目录，请禁用发现：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -282,22 +250,17 @@ OpenClaw 会话，而 Codex harness 会按需创建或恢复其侧车 app-server
|
||||
}
|
||||
```
|
||||
|
||||
## App-server 连接与策略
|
||||
## 应用服务器连接与策略
|
||||
|
||||
默认情况下，插件会使用以下命令在本地启动 Codex：
|
||||
默认情况下，插件会在本地通过以下命令启动 Codex：
|
||||
|
||||
```bash
|
||||
codex app-server --listen stdio://
|
||||
```
|
||||
|
||||
默认情况下，OpenClaw 会以 YOLO 模式启动本地 Codex harness 会话：
|
||||
`approvalPolicy: "never"`、`approvalsReviewer: "user"`，以及
|
||||
`sandbox: "danger-full-access"`。这是用于
|
||||
自治 heartbeat 的受信任本地运维姿态：Codex 可以使用 shell 和网络工具，而不会
|
||||
停在无人响应的原生审批提示上。
|
||||
默认情况下，OpenClaw 会以 YOLO 模式启动本地 Codex 测试框架会话：`approvalPolicy: "never"`、`approvalsReviewer: "user"` 和 `sandbox: "danger-full-access"`。这是用于自主心跳的受信任本地操作员姿态：Codex 可以使用 shell 和网络工具，而不会停在无人响应的原生审批提示上。
|
||||
|
||||
若要启用 Codex guardian 审查式审批，请设置 `appServer.mode:
|
||||
"guardian"`：
|
||||
如果你想启用由 Codex guardian 审核的审批，请设置 `appServer.mode: "guardian"`：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -317,11 +280,11 @@ codex app-server --listen stdio://
|
||||
}
|
||||
```
|
||||
|
||||
Guardian 是原生 Codex 审批审查者。当 Codex 请求离开沙箱、写入工作区之外的内容，或添加像网络访问这样的权限时，Codex 会将该审批请求路由给一个 reviewer subagent，而不是弹出人工提示。该 reviewer 会应用 Codex 的风险框架，并批准或拒绝具体请求。当你希望比 YOLO 模式拥有更多护栏，但仍需要无人值守智能体持续推进时，请使用 Guardian。
|
||||
Guardian 是 Codex 的原生审批审核器。当 Codex 请求离开沙箱、在工作区外写入，或添加诸如网络访问之类的权限时，Codex 会将该审批请求路由给一个 reviewer 子智能体，而不是弹出人工提示。该 reviewer 会应用 Codex 的风险框架，并批准或拒绝该具体请求。如果你希望比 YOLO 模式有更多保护措施，但仍需要无人值守的智能体继续推进任务，请使用 Guardian。
|
||||
|
||||
`guardian` 预设会展开为 `approvalPolicy: "on-request"`、`approvalsReviewer: "guardian_subagent"` 和 `sandbox: "workspace-write"`。单独的策略字段仍会覆盖 `mode`，因此高级部署可以将该预设与显式选择混合使用。
|
||||
`guardian` 预设会展开为 `approvalPolicy: "on-request"`、`approvalsReviewer: "guardian_subagent"` 和 `sandbox: "workspace-write"`。各个单独的策略字段仍然会覆盖 `mode`，因此高级部署可以将该预设与显式设置混合使用。
|
||||
|
||||
对于已在运行的 app-server，请使用 WebSocket 传输：
|
||||
对于已经在运行的应用服务器，请使用 WebSocket 传输：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -348,19 +311,19 @@ Guardian 是原生 Codex 审批审查者。当 Codex 请求离开沙箱、写入
|
||||
| 字段 | 默认值 | 含义 |
|
||||
| ------------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------- |
|
||||
| `transport` | `"stdio"` | `"stdio"` 会启动 Codex；`"websocket"` 会连接到 `url`。 |
|
||||
| `command` | `"codex"` | stdio 传输所使用的可执行文件。 |
|
||||
| `args` | `["app-server", "--listen", "stdio://"]` | stdio 传输所使用的参数。 |
|
||||
| `url` | 未设置 | WebSocket app-server URL。 |
|
||||
| `authToken` | 未设置 | WebSocket 传输的 Bearer token。 |
|
||||
| `headers` | `{}` | 额外的 WebSocket headers。 |
|
||||
| `requestTimeoutMs` | `60000` | app-server 控制平面调用的超时时间。 |
|
||||
| `mode` | `"yolo"` | YOLO 或 guardian 审查执行的预设。 |
|
||||
| `approvalPolicy` | `"never"` | 发送到线程启动/恢复/轮次的原生 Codex 审批策略。 |
|
||||
| `command` | `"codex"` | 用于 stdio 传输的可执行文件。 |
|
||||
| `args` | `["app-server", "--listen", "stdio://"]` | 用于 stdio 传输的参数。 |
|
||||
| `url` | 未设置 | WebSocket 应用服务器 URL。 |
|
||||
| `authToken` | 未设置 | 用于 WebSocket 传输的 Bearer token。 |
|
||||
| `headers` | `{}` | 额外的 WebSocket 标头。 |
|
||||
| `requestTimeoutMs` | `60000` | 应用服务器控制平面调用的超时时间。 |
|
||||
| `mode` | `"yolo"` | 用于 YOLO 或 guardian 审核执行的预设。 |
|
||||
| `approvalPolicy` | `"never"` | 发送到线程启动/恢复/回合的原生 Codex 审批策略。 |
|
||||
| `sandbox` | `"danger-full-access"` | 发送到线程启动/恢复的原生 Codex 沙箱模式。 |
|
||||
| `approvalsReviewer` | `"user"` | 使用 `"guardian_subagent"` 可让 Codex Guardian 审查提示。 |
|
||||
| `serviceTier` | 未设置 | 可选的 Codex app-server 服务层级：`"fast"`、`"flex"` 或 `null`。无效的旧版值会被忽略。
|
||||
| `approvalsReviewer` | `"user"` | 使用 `"guardian_subagent"` 让 Codex Guardian 审核提示。 |
|
||||
| `serviceTier` | 未设置 | 可选的 Codex 应用服务器服务层级：`"fast"`、`"flex"` 或 `null`。无效的旧值会被忽略。 |
|
||||
|
||||
较旧的环境变量在匹配的配置字段未设置时，仍可作为本地测试的回退方式：
|
||||
当对应配置字段未设置时，较旧的环境变量仍可作为本地测试的回退方式继续使用：
|
||||
|
||||
- `OPENCLAW_CODEX_APP_SERVER_BIN`
|
||||
- `OPENCLAW_CODEX_APP_SERVER_ARGS`
|
||||
@ -368,10 +331,7 @@ Guardian 是原生 Codex 审批审查者。当 Codex 请求离开沙箱、写入
|
||||
- `OPENCLAW_CODEX_APP_SERVER_APPROVAL_POLICY`
|
||||
- `OPENCLAW_CODEX_APP_SERVER_SANDBOX`
|
||||
|
||||
`OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1` 已被移除。请改用
|
||||
`plugins.entries.codex.config.appServer.mode: "guardian"`，或者在一次性本地测试中使用
|
||||
`OPENCLAW_CODEX_APP_SERVER_MODE=guardian`。对于可重复部署，优先使用配置，
|
||||
因为这样可以将插件行为与 Codex harness 其余设置一起放在同一个已审查文件中。
|
||||
`OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1` 已被移除。请改用 `plugins.entries.codex.config.appServer.mode: "guardian"`，或者在一次性本地测试中使用 `OPENCLAW_CODEX_APP_SERVER_MODE=guardian`。对于可重复部署，优先使用配置，因为这样可以将插件行为与 Codex 测试框架其余设置保存在同一个经过审查的文件中。
|
||||
|
||||
## 常见配方
|
||||
|
||||
@ -389,7 +349,7 @@ Guardian 是原生 Codex 审批审查者。当 Codex 请求离开沙箱、写入
|
||||
}
|
||||
```
|
||||
|
||||
仅验证 Codex harness，并禁用 PI 回退：
|
||||
仅使用 Codex 的测试框架验证，并禁用 Pi 回退：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -406,7 +366,7 @@ Guardian 是原生 Codex 审批审查者。当 Codex 请求离开沙箱、写入
|
||||
}
|
||||
```
|
||||
|
||||
Guardian 审查式 Codex 审批：
|
||||
由 Guardian 审核的 Codex 审批：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -428,7 +388,7 @@ Guardian 审查式 Codex 审批：
|
||||
}
|
||||
```
|
||||
|
||||
使用显式 headers 的远程 app-server：
|
||||
带显式标头的远程应用服务器：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -451,83 +411,57 @@ Guardian 审查式 Codex 审批：
|
||||
}
|
||||
```
|
||||
|
||||
模型切换仍由 OpenClaw 控制。当一个 OpenClaw 会话附加到已有
|
||||
Codex 线程时，下一轮会再次将当前选中的
|
||||
OpenAI 模型、提供商、审批策略、沙箱和服务层级发送给
|
||||
app-server。将 `openai/gpt-5.5` 切换为 `openai/gpt-5.2` 时，会保留
|
||||
线程绑定，但会要求 Codex 使用新选中的模型继续运行。
|
||||
模型切换仍由 OpenClaw 控制。当 OpenClaw 会话附加到现有 Codex 线程时，下一回合会再次将当前选中的 OpenAI 模型、provider、审批策略、沙箱和服务层级发送给应用服务器。从 `openai/gpt-5.5` 切换到 `openai/gpt-5.2` 会保留线程绑定，但会要求 Codex 使用新选中的模型继续执行。
|
||||
|
||||
## Codex 命令
|
||||
|
||||
内置插件将 `/codex` 注册为授权的斜杠命令。它是通用的，适用于任何支持 OpenClaw 文本命令的渠道。
|
||||
内置插件将 `/codex` 注册为已授权的斜杠命令。它是通用命令，可用于任何支持 OpenClaw 文本命令的渠道。
|
||||
|
||||
常见形式：
|
||||
|
||||
- `/codex status` 显示实时 app-server 连接性、模型、账户、速率限制、MCP 服务器和 skills。
|
||||
- `/codex models` 列出实时 Codex app-server 模型。
|
||||
- `/codex status` 显示实时的应用服务器连接状态、模型、账户、速率限制、MCP 服务器和技能。
|
||||
- `/codex models` 列出实时的 Codex 应用服务器模型。
|
||||
- `/codex threads [filter]` 列出最近的 Codex 线程。
|
||||
- `/codex resume <thread-id>` 将当前 OpenClaw 会话附加到现有 Codex 线程。
|
||||
- `/codex compact` 请求 Codex app-server 对附加线程执行压缩总结。
|
||||
- `/codex review` 为附加线程启动 Codex 原生审查。
|
||||
- `/codex compact` 请求 Codex 应用服务器压缩当前附加的线程。
|
||||
- `/codex review` 为当前附加的线程启动 Codex 原生审查。
|
||||
- `/codex account` 显示账户和速率限制状态。
|
||||
- `/codex mcp` 列出 Codex app-server MCP 服务器状态。
|
||||
- `/codex skills` 列出 Codex app-server Skills。
|
||||
- `/codex mcp` 列出 Codex 应用服务器 MCP 服务器状态。
|
||||
- `/codex skills` 列出 Codex 应用服务器 Skills。
|
||||
|
||||
`/codex resume` 会写入与 harness 正常轮次所使用的相同侧车绑定文件。下一条消息到来时，OpenClaw 会恢复该 Codex 线程，将当前选中的 OpenClaw `codex/*` 模型传入 app-server，并保持扩展历史启用。
|
||||
`/codex resume` 会写入与测试框架在正常回合中使用的同一个 sidecar 绑定文件。在下一条消息时，OpenClaw 会恢复该 Codex 线程，将当前选中的 OpenClaw 模型传入应用服务器，并保持启用扩展历史记录。
|
||||
|
||||
该命令表面要求 Codex app-server 版本为 `0.118.0` 或更新。若未来版本或自定义 app-server 未暴露某个 JSON-RPC 方法，单个控制方法会报告为 `unsupported by this Codex app-server`。
|
||||
该命令界面要求 Codex 应用服务器版本为 `0.118.0` 或更高。如果未来版本或自定义应用服务器未公开某个 JSON-RPC 方法，则对应的单个控制方法会显示为 `unsupported by this Codex app-server`。
|
||||
|
||||
## 工具、媒体与压缩总结
|
||||
## 工具、媒体和压缩
|
||||
|
||||
Codex harness 只改变底层嵌入式智能体执行器。
|
||||
Codex 测试框架只会更改底层嵌入式智能体执行器。
|
||||
|
||||
OpenClaw 仍然构建工具列表，并从
|
||||
harness 接收动态工具结果。文本、图像、视频、音乐、TTS、审批以及消息工具输出
|
||||
仍然通过正常的 OpenClaw 传递路径流动。
|
||||
OpenClaw 仍然负责构建工具列表，并从测试框架接收动态工具结果。文本、图像、视频、音乐、TTS、审批以及消息工具输出，都会继续通过正常的 OpenClaw 传输路径处理。
|
||||
|
||||
当 Codex 将 `_meta.codex_approval_kind` 标记为
|
||||
`"mcp_tool_call"` 时，Codex MCP 工具审批请求会通过 OpenClaw 的插件审批流程进行路由；其他请求获取输入的情形以及自由格式输入请求仍然会失败即关闭。
|
||||
当 Codex 将 `_meta.codex_approval_kind` 标记为 `"mcp_tool_call"` 时，Codex MCP 工具审批引导会通过 OpenClaw 的插件审批流程进行路由；其他引导请求和自由形式输入请求仍会默认拒绝。
|
||||
|
||||
当所选模型使用 Codex harness 时，原生线程压缩总结会委托给
|
||||
Codex app-server。OpenClaw 会保留转录镜像，用于渠道历史、
|
||||
搜索、`/new`、`/reset`，以及未来的模型或 harness 切换。该
|
||||
镜像包括用户提示词、最终助手文本，以及在 app-server 发出时的轻量级 Codex
|
||||
推理或计划记录。目前，OpenClaw 只记录原生压缩总结开始与完成信号。它尚未暴露
|
||||
人类可读的压缩总结摘要，也未提供可审计的列表来说明 Codex
|
||||
在压缩总结后保留了哪些条目。
|
||||
当选中的模型使用 Codex 测试框架时，原生线程压缩会委托给 Codex 应用服务器。OpenClaw 会继续保留一个转录镜像，用于渠道历史记录、搜索、`/new`、`/reset` 以及未来的模型或测试框架切换。该镜像包括用户提示、最终助手文本，以及应用服务器发出时的轻量级 Codex 推理或计划记录。目前，OpenClaw 只记录原生压缩的开始和完成信号。它尚未公开可供人类阅读的压缩摘要，也无法提供 Codex 在压缩后保留了哪些条目的可审计列表。
|
||||
|
||||
媒体生成不需要 PI。图像、视频、音乐、PDF、TTS 以及媒体
|
||||
理解仍然继续使用匹配的提供商/模型设置，例如
|
||||
`agents.defaults.imageGenerationModel`、`videoGenerationModel`、`pdfModel` 和
|
||||
`messages.tts`。
|
||||
媒体生成功能不依赖 Pi。图像、视频、音乐、PDF、TTS 和媒体理解仍会继续使用对应的 provider/模型设置，例如 `agents.defaults.imageGenerationModel`、`videoGenerationModel`、`pdfModel` 和 `messages.tts`。
|
||||
|
||||
## 故障排除
|
||||
|
||||
**`/model` 中看不到 Codex：** 启用 `plugins.entries.codex.enabled`，
|
||||
设置一个 `codex/*` 模型引用，或检查 `plugins.allow` 是否排除了 `codex`。
|
||||
**`/model` 中看不到 Codex：** 启用 `plugins.entries.codex.enabled`，选择带有 `embeddedHarness.runtime: "codex"` 的 `openai/gpt-*` 模型（或旧版 `codex/*` 引用），并检查 `plugins.allow` 是否排除了 `codex`。
|
||||
|
||||
**OpenClaw 使用了 PI 而不是 Codex：** 如果没有 Codex harness 接管该运行，
|
||||
OpenClaw 可能会使用 PI 作为兼容性后端。测试时请设置
|
||||
`embeddedHarness.runtime: "codex"` 以强制选择 Codex，或设置
|
||||
`embeddedHarness.fallback: "none"`，使得当没有匹配的插件 harness 时直接失败。一旦
|
||||
Codex app-server 被选中，其失败会直接暴露出来，而无需额外的
|
||||
回退配置。
|
||||
**OpenClaw 使用 Pi 而不是 Codex：** 如果没有任何 Codex 测试框架声明处理该运行，OpenClaw 可能会使用 Pi 作为兼容后端。测试时请设置 `embeddedHarness.runtime: "codex"` 以强制选择 Codex，或设置 `embeddedHarness.fallback: "none"`，以便在没有匹配的插件测试框架时报错。一旦选择了 Codex 应用服务器，其失败会直接暴露出来，不需要额外的回退配置。
|
||||
|
||||
**app-server 被拒绝：** 升级 Codex，确保 app-server 握手
|
||||
报告版本为 `0.118.0` 或更新。
|
||||
**应用服务器被拒绝：** 升级 Codex，使应用服务器握手报告的版本为 `0.118.0` 或更高。
|
||||
|
||||
**模型发现很慢：** 调低 `plugins.entries.codex.config.discovery.timeoutMs`
|
||||
或禁用发现。
|
||||
**模型发现过慢：** 降低 `plugins.entries.codex.config.discovery.timeoutMs` 或禁用发现。
|
||||
|
||||
**WebSocket 传输立即失败：** 检查 `appServer.url`、`authToken`，
|
||||
以及远程 app-server 是否使用相同版本的 Codex app-server 协议。
|
||||
**WebSocket 传输立即失败：** 检查 `appServer.url`、`authToken`，以及远程应用服务器是否使用相同版本的 Codex 应用服务器协议。
|
||||
|
||||
**非 Codex 模型使用了 PI：** 这是预期行为。Codex harness 只会接管
|
||||
`codex/*` 模型引用。
|
||||
**非 Codex 模型使用了 Pi：** 这是预期行为，除非你强制设置了 `embeddedHarness.runtime: "codex"`（或选择了旧版 `codex/*` 引用）。普通的 `openai/gpt-*` 和其他 provider 引用都会继续使用其正常的 provider 路径。
|
||||
|
||||
## 相关内容
|
||||
|
||||
- [智能体 Harness 插件](/zh-CN/plugins/sdk-agent-harness)
|
||||
- [智能体测试框架插件](/zh-CN/plugins/sdk-agent-harness)
|
||||
- [模型提供商](/zh-CN/concepts/model-providers)
|
||||
- [配置参考](/zh-CN/gateway/configuration-reference)
|
||||
- [测试](/zh-CN/help/testing#live-codex-app-server-harness-smoke)
|
||||
|
||||
@ -1,55 +1,49 @@
|
||||
---
|
||||
read_when:
|
||||
- 你正在更改内嵌智能体运行时或 harness 注册表
|
||||
- 你正在更改嵌入式智能体运行时或 harness 注册表
|
||||
- 你正在从内置或受信任插件注册一个智能体 harness
|
||||
- 你需要了解 Codex 插件与模型提供商之间的关系
|
||||
sidebarTitle: Agent Harness
|
||||
summary: 供替换底层内嵌智能体执行器的插件使用的实验性 SDK 接口
|
||||
summary: 用于替换底层嵌入式智能体执行器的插件实验性 SDK 接口
|
||||
title: 智能体 harness 插件
|
||||
x-i18n:
|
||||
generated_at: "2026-04-23T20:57:19Z"
|
||||
generated_at: "2026-04-23T21:49:30Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 69d0c4febbc0f0397d4fc8a212039a2d78764798b82f48e600daf68626826904
|
||||
source_hash: 966d685627b11651fbd0c7fe00a7e3e412c14b39511845ecfcdc4366fa9f8767
|
||||
source_path: plugins/sdk-agent-harness.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
一个**智能体 harness** 是执行一次已准备好的 OpenClaw 智能体轮次的底层执行器。
|
||||
它不是模型提供商，不是渠道，也不是工具注册表。
|
||||
**智能体 harness** 是为一个已准备好的 OpenClaw 智能体轮次提供的底层执行器。它不是模型提供商，不是渠道，也不是工具注册表。
|
||||
|
||||
仅应将这个接口用于内置或受信任的原生插件。该合约
|
||||
仍然是实验性的，因为其参数类型有意镜像当前的
|
||||
内嵌执行器。
|
||||
仅对内置或受信任的原生插件使用此接口。该契约仍然是实验性的，因为参数类型有意映射当前的嵌入式运行器。
|
||||
|
||||
## 何时使用 harness
|
||||
|
||||
当某个模型家族拥有自己的原生会话
|
||||
运行时，而普通的 OpenClaw 提供商传输抽象并不合适时，请注册一个智能体 harness。
|
||||
当某个模型家族拥有自己的原生会话运行时，而常规的 OpenClaw 提供商传输层并不是合适抽象时，请注册一个智能体 harness。
|
||||
|
||||
示例：
|
||||
|
||||
- 拥有线程和压缩逻辑的原生编码智能体服务器
|
||||
- 必须流式传输原生计划/推理/工具事件的本地 CLI 或 daemon
|
||||
- 除 OpenClaw 会话转录外，还需要自身 resume id 的模型运行时
|
||||
- 拥有线程与压缩能力的原生编码智能体服务器
|
||||
- 必须流式传输原生计划/推理/工具事件的本地 CLI 或守护进程
|
||||
- 除了 OpenClaw 会话 transcript 之外，还需要自己的 resume id 的模型运行时
|
||||
|
||||
不要仅仅为了增加一个新的 LLM API 就注册 harness。对于普通的 HTTP 或
|
||||
WebSocket 模型 API，请构建一个[提供商插件](/zh-CN/plugins/sdk-provider-plugins)。
|
||||
**不要** 仅仅为了添加一个新的 LLM API 而注册 harness。对于常规的 HTTP 或 WebSocket 模型 API，请构建一个[提供商插件](/zh-CN/plugins/sdk-provider-plugins)。
|
||||
|
||||
## 核心仍然负责什么
|
||||
## 核心仍负责的内容
|
||||
|
||||
在选择 harness 之前，OpenClaw 已经解析好了：
|
||||
在选择 harness 之前，OpenClaw 已经解析了：
|
||||
|
||||
- 提供商和模型
|
||||
- 运行时身份验证状态
|
||||
- thinking 级别和上下文预算
|
||||
- OpenClaw 转录/会话文件
|
||||
- provider 和 model
|
||||
- 运行时认证状态
|
||||
- 思考级别和上下文预算
|
||||
- OpenClaw transcript/会话文件
|
||||
- 工作区、沙箱和工具策略
|
||||
- 渠道回复回调和流式回调
|
||||
- 渠道回复回调和流式传输回调
|
||||
- 模型回退和实时模型切换策略
|
||||
|
||||
这种拆分是有意设计的。Harness 负责运行一次已准备好的尝试；它不会选择
|
||||
提供商、替代渠道投递，或静默切换模型。
|
||||
这种拆分是有意设计的。harness 负责运行一个已准备好的尝试；它不会选择提供商、替换渠道投递，也不会静默切换模型。
|
||||
|
||||
## 注册 harness
|
||||
|
||||
@ -70,9 +64,9 @@ const myHarness: AgentHarness = {
|
||||
},
|
||||
|
||||
async runAttempt(params) {
|
||||
// 启动或恢复你的原生线程。
|
||||
// 使用 params.prompt、params.tools、params.images、params.onPartialReply、
|
||||
// params.onAgentEvent，以及其他已准备好的尝试字段。
|
||||
// Start or resume your native thread.
|
||||
// Use params.prompt, params.tools, params.images, params.onPartialReply,
|
||||
// params.onAgentEvent, and the other prepared attempt fields.
|
||||
return await runMyNativeTurn(params);
|
||||
},
|
||||
};
|
||||
@ -89,91 +83,55 @@ export default definePluginEntry({
|
||||
|
||||
## 选择策略
|
||||
|
||||
OpenClaw 会在提供商/模型解析之后选择 harness：
|
||||
OpenClaw 会在 provider/model 解析之后选择一个 harness：
|
||||
|
||||
1. 现有会话中记录的 harness id 优先生效，因此配置/环境变量更改不会
|
||||
热切换该转录到另一个运行时。
|
||||
2. `OPENCLAW_AGENT_RUNTIME=<id>` 会为尚未固定的会话强制选择该 id 对应的已注册 harness。
|
||||
3. `OPENCLAW_AGENT_RUNTIME=pi` 会强制使用内置 PI harness。
|
||||
4. `OPENCLAW_AGENT_RUNTIME=auto` 会让已注册 harness 询问自己是否支持
|
||||
当前解析出的提供商/模型。
|
||||
5. 如果没有任何已注册 harness 匹配，则 OpenClaw 使用 PI，除非
|
||||
PI 回退已被禁用。
|
||||
1. 已有会话中记录的 harness id 优先生效，因此配置/环境变量的变化不会将该 transcript 热切换到另一个运行时。
|
||||
2. `OPENCLAW_AGENT_RUNTIME=<id>` 会为尚未固定的会话强制使用具有该 id 的已注册 harness。
|
||||
3. `OPENCLAW_AGENT_RUNTIME=pi` 会强制使用内置的 PI harness。
|
||||
4. `OPENCLAW_AGENT_RUNTIME=auto` 会让已注册的 harness 判断它们是否支持已解析的 provider/model。
|
||||
5. 如果没有匹配的已注册 harness，OpenClaw 会使用 PI，除非已禁用 PI 回退。
|
||||
|
||||
插件 harness 失败会表现为运行失败。在 `auto` 模式下，只有在没有任何已注册插件 harness 支持当前解析出的
|
||||
提供商/模型时，才会使用 PI 回退。一旦某个插件 harness 已经声明接管该次运行，OpenClaw 就不会再通过 PI 重新回放同一轮，因为这可能改变身份验证/运行时语义
|
||||
或导致副作用重复。
|
||||
插件 harness 失败会以运行失败的形式呈现。在 `auto` 模式下，只有当没有已注册的插件 harness 支持已解析的 provider/model 时，才会使用 PI 回退。一旦某个插件 harness 已经接管一次运行，OpenClaw 就不会再通过 PI 重放同一轮次，因为这可能改变认证/运行时语义或造成副作用重复。
|
||||
|
||||
选定的 harness id 会在一次内嵌运行后与会话 id 一起持久化。
|
||||
在引入 harness 固定前创建的旧会话，一旦有转录历史，就会被视为固定到 PI。
|
||||
在 PI 和原生插件 harness 之间切换时，请使用一个新的/已重置的会话。
|
||||
`/status` 会在 `Fast` 旁边显示诸如 `codex`
|
||||
这样的非默认 harness id；PI 会被隐藏，因为它是默认兼容路径。
|
||||
在一次嵌入式运行之后，所选的 harness id 会与 session id 一起持久化。对于在 harness 固定机制出现之前创建的旧会话，一旦其拥有 transcript 历史，就会被视为固定到 PI。要在 PI 与原生插件 harness 之间切换，请使用新的/已重置的会话。`/status` 会在 `Fast` 旁边显示诸如 `codex` 这样的非默认 harness id；由于 PI 是默认兼容路径，因此会被隐藏。如果所选 harness 出乎你的预期，请启用 `agents/harness` 调试日志，并检查 Gateway 网关中的结构化 `agent harness selected` 记录。其中包含所选 harness id、选择原因、运行时/回退策略，以及在 `auto` 模式下各插件候选项的支持结果。
|
||||
|
||||
内置 Codex 插件将 `codex` 注册为它的 harness id。核心将其视为普通插件 harness id；
|
||||
Codex 特定别名应归属于插件或运维配置，而不是共享运行时选择器。
|
||||
内置的 Codex 插件将 `codex` 注册为其 harness id。核心将其视为普通的插件 harness id；Codex 专用别名应放在插件或运维配置中，而不是共享运行时选择器中。
|
||||
|
||||
## 提供商与 harness 的配对
|
||||
## provider 与 harness 配对
|
||||
|
||||
大多数 harness 也应同时注册一个提供商。提供商会让模型引用、
|
||||
身份验证状态、模型元数据以及 `/model` 选择对 OpenClaw 的其他部分可见。
|
||||
然后 harness 在 `supports(...)` 中声明自己接管该提供商。
|
||||
大多数 harness 也应该注册一个 provider。provider 会让模型引用、认证状态、模型元数据和 `/model` 选择对 OpenClaw 的其他部分可见。随后，harness 会在 `supports(...)` 中声明接管该 provider。
|
||||
|
||||
内置 Codex 插件采用了这种模式：
|
||||
内置的 Codex 插件遵循这一模式：
|
||||
|
||||
- provider id：`codex`
|
||||
- 用户模型引用：规范形式为 `openai/gpt-5.5`，并配合
|
||||
`embeddedHarness.runtime: "codex"`；旧版 `codex/gpt-*` 引用仍然为了兼容而被接受
|
||||
- 用户模型引用：规范形式为 `openai/gpt-5.5` 加上 `embeddedHarness.runtime: "codex"`；旧版 `codex/gpt-*` 引用仍为兼容性而继续接受
|
||||
- harness id：`codex`
|
||||
- 身份验证：合成的提供商可用性，因为 Codex harness 拥有原生 Codex 登录/会话
|
||||
- app-server 请求：OpenClaw 向 Codex 发送裸模型 id，并让
|
||||
harness 与原生 app-server 协议通信
|
||||
- 认证：合成的 provider 可用性，因为 Codex harness 负责原生 Codex 登录/会话
|
||||
- app-server 请求：OpenClaw 会将裸模型 id 发送给 Codex，并让 harness 与原生 app-server 协议通信
|
||||
|
||||
Codex 插件是增量式的。普通的 `openai/gpt-*` 引用仍然走
|
||||
标准 OpenClaw 提供商路径，除非你通过
|
||||
`embeddedHarness.runtime: "codex"` 强制使用 Codex harness。旧版 `codex/gpt-*` 引用
|
||||
仍然会为了兼容而选择 Codex 提供商和 harness。
|
||||
Codex 插件是增量式的。普通的 `openai/gpt-*` 引用仍会使用常规的 OpenClaw provider 路径，除非你通过 `embeddedHarness.runtime: "codex"` 强制使用 Codex harness。较旧的 `codex/gpt-*` 引用仍会为兼容性而选择 Codex provider 和 harness。
|
||||
|
||||
关于运维设置、模型前缀示例和仅 Codex 配置，请参见
|
||||
[Codex Harness](/zh-CN/plugins/codex-harness)。
|
||||
有关运维设置、模型前缀示例和仅限 Codex 的配置，请参阅 [Codex Harness](/zh-CN/plugins/codex-harness)。
|
||||
|
||||
OpenClaw 要求 Codex app-server 版本为 `0.118.0` 或更高。Codex 插件会检查
|
||||
app-server 初始化握手，并阻止较旧或未标明版本的服务器，
|
||||
以确保 OpenClaw 仅在其已测试过的协议接口上运行。
|
||||
OpenClaw 要求 Codex app-server 为 `0.118.0` 或更新版本。Codex 插件会检查 app-server 初始化握手，并阻止较旧或未标注版本的服务器，以确保 OpenClaw 仅在其已测试过的协议接口上运行。
|
||||
|
||||
### Codex app-server 工具结果中间件
|
||||
### Codex app-server tool-result 中间件
|
||||
|
||||
当其 manifest 声明 `contracts.embeddedExtensionFactories: ["codex-app-server"]` 时，
|
||||
内置插件还可以通过 `api.registerCodexAppServerExtensionFactory(...)` 挂接 Codex app-server 特定的 `tool_result`
|
||||
中间件。
|
||||
这是受信任插件的扩展点，用于在原生 Codex harness 内部运行异步工具结果转换，然后再将工具输出映射回 OpenClaw 转录。
|
||||
当插件清单声明 `contracts.embeddedExtensionFactories: ["codex-app-server"]` 时，内置插件还可以通过 `api.registerCodexAppServerExtensionFactory(...)` 挂载特定于 Codex app-server 的 `tool_result` 中间件。这是一个受信任插件的扩展点，适用于那些需要在原生 Codex harness 内部运行的异步工具结果转换，然后再将工具输出投射回 OpenClaw transcript。
|
||||
|
||||
### 原生 Codex harness 模式
|
||||
|
||||
内置的 `codex` harness 是内嵌 OpenClaw
|
||||
智能体轮次的原生 Codex 模式。请先启用内置 `codex` 插件，并且如果你的配置使用了严格 allowlist，请将 `codex` 加入
|
||||
`plugins.allow`。新配置应使用 `openai/gpt-*` 并配合 `embeddedHarness.runtime: "codex"`。旧版
|
||||
`openai-codex/*` 和 `codex/*` 模型引用仍保留为兼容别名。
|
||||
内置的 `codex` harness 是嵌入式 OpenClaw 智能体轮次的原生 Codex 模式。请先启用内置的 `codex` 插件；如果你的配置使用了严格的 allowlist，还要在 `plugins.allow` 中包含 `codex`。新配置应使用 `openai/gpt-*` 搭配 `embeddedHarness.runtime: "codex"`。旧版 `openai-codex/*` 和 `codex/*` 模型引用仍保留为兼容性别名。
|
||||
|
||||
当该模式运行时，Codex 拥有原生线程 id、恢复行为、
|
||||
压缩逻辑和 app-server 执行。OpenClaw 仍负责聊天渠道、
|
||||
可见转录镜像、工具策略、审批、媒体投递和会话
|
||||
选择。当你需要证明只有 Codex
|
||||
app-server 路径能够接管该次运行时，请使用 `embeddedHarness.runtime: "codex"` 并配合
|
||||
`embeddedHarness.fallback: "none"`。该配置只是一个选择保护：
|
||||
Codex app-server 失败本来就会直接失败，而不是通过 PI 重试。
|
||||
当该模式运行时，Codex 负责原生线程 id、resume 行为、压缩和 app-server 执行。OpenClaw 仍负责聊天渠道、可见 transcript 镜像、工具策略、审批、媒体投递和会话选择。当你需要证明只有 Codex app-server 路径可以接管该运行时，请使用 `embeddedHarness.runtime: "codex"` 搭配 `embeddedHarness.fallback: "none"`。该配置仅是一个选择保护措施：Codex app-server 失败本来就会直接失败，而不会通过 PI 重试。
|
||||
|
||||
## 禁用 PI 回退
|
||||
|
||||
默认情况下，OpenClaw 会以 `agents.defaults.embeddedHarness`
|
||||
设置为 `{ runtime: "auto", fallback: "pi" }` 来运行内嵌智能体。在 `auto` 模式下，已注册插件
|
||||
harness 可以接管某个提供商/模型对。如果没有任何匹配，OpenClaw 会回退到 PI。
|
||||
默认情况下，OpenClaw 运行嵌入式智能体时，`agents.defaults.embeddedHarness` 设置为 `{ runtime: "auto", fallback: "pi" }`。在 `auto` 模式下，已注册的插件 harness 可以接管某个 provider/model 组合。如果没有匹配项，OpenClaw 会回退到 PI。
|
||||
|
||||
当你需要在缺少插件 harness 选择时直接失败，而不是改用 PI，
|
||||
请设置 `fallback: "none"`。已选中的插件 harness 失败本来就会硬失败。
|
||||
这不会阻止显式的 `runtime: "pi"` 或 `OPENCLAW_AGENT_RUNTIME=pi`。
|
||||
当你需要在缺少插件 harness 选择时直接失败，而不是使用 PI 时，请设置 `fallback: "none"`。已选中的插件 harness 失败本来就会硬失败。这不会阻止显式的 `runtime: "pi"` 或 `OPENCLAW_AGENT_RUNTIME=pi`。
|
||||
|
||||
对于仅 Codex 的内嵌运行：
|
||||
对于仅使用 Codex 的嵌入式运行：
|
||||
|
||||
```json
|
||||
{
|
||||
@ -189,7 +147,7 @@ harness 可以接管某个提供商/模型对。如果没有任何匹配，OpenC
|
||||
}
|
||||
```
|
||||
|
||||
如果你希望任何已注册插件 harness 都可以接管匹配模型，但绝不希望 OpenClaw 静默回退到 PI，请保持 `runtime: "auto"` 并禁用回退：
|
||||
如果你希望任何已注册的插件 harness 都可以接管匹配的模型，但又不希望 OpenClaw 静默回退到 PI，请保留 `runtime: "auto"` 并禁用回退：
|
||||
|
||||
```json
|
||||
{
|
||||
@ -204,7 +162,7 @@ harness 可以接管某个提供商/模型对。如果没有任何匹配，OpenC
|
||||
}
|
||||
```
|
||||
|
||||
按智能体划分的覆盖使用相同结构：
|
||||
每个智能体的覆盖项使用相同的结构：
|
||||
|
||||
```json
|
||||
{
|
||||
@ -229,8 +187,7 @@ harness 可以接管某个提供商/模型对。如果没有任何匹配，OpenC
|
||||
}
|
||||
```
|
||||
|
||||
`OPENCLAW_AGENT_RUNTIME` 仍然会覆盖已配置的运行时。使用
|
||||
`OPENCLAW_AGENT_HARNESS_FALLBACK=none` 可从环境变量中禁用 PI 回退。
|
||||
`OPENCLAW_AGENT_RUNTIME` 仍会覆盖已配置的运行时。使用 `OPENCLAW_AGENT_HARNESS_FALLBACK=none` 可以通过环境变量禁用 PI 回退。
|
||||
|
||||
```bash
|
||||
OPENCLAW_AGENT_RUNTIME=codex \
|
||||
@ -238,49 +195,36 @@ OPENCLAW_AGENT_HARNESS_FALLBACK=none \
|
||||
openclaw gateway run
|
||||
```
|
||||
|
||||
禁用回退后，当所请求的 harness 未注册、
|
||||
不支持已解析的提供商/模型，或在产生轮次副作用前失败时，会话会提前失败。
|
||||
这对于仅 Codex 部署以及必须证明 Codex
|
||||
app-server 路径确实被使用的在线测试来说，是有意为之的行为。
|
||||
禁用回退后，如果请求的 harness 未注册、不支持已解析的 provider/model，或者在产生轮次副作用之前就已失败，则会话会提前失败。对于仅使用 Codex 的部署，以及必须证明 Codex app-server 路径确实在使用中的实时测试，这是有意设计的。
|
||||
|
||||
此设置仅控制内嵌智能体 harness。它不会禁用
|
||||
图片、视频、音乐、TTS、PDF 或其他按提供商划分的模型路由。
|
||||
此设置仅控制嵌入式智能体 harness。它不会禁用图像、视频、音乐、TTS、PDF 或其他提供商特定的模型路由。
|
||||
|
||||
## 原生会话与转录镜像
|
||||
## 原生会话与 transcript 镜像
|
||||
|
||||
Harness 可以保留原生 session id、thread id 或 daemon 侧 resume token。
|
||||
请将这种绑定与 OpenClaw 会话显式关联，并持续
|
||||
将用户可见的助手/工具输出镜像到 OpenClaw 转录中。
|
||||
harness 可能会保留原生 session id、thread id 或守护进程侧的 resume token。请将这种绑定显式地与 OpenClaw 会话关联起来，并继续将用户可见的助手/工具输出镜像到 OpenClaw transcript 中。
|
||||
|
||||
OpenClaw 转录仍然是以下内容的兼容层：
|
||||
OpenClaw transcript 仍然是以下内容的兼容层：
|
||||
|
||||
- 渠道可见的会话历史
|
||||
- 转录搜索和索引
|
||||
- 在后续轮次中切换回内置 PI harness
|
||||
- transcript 搜索与索引
|
||||
- 在后续轮次中切换回内置的 PI harness
|
||||
- 通用的 `/new`、`/reset` 和会话删除行为
|
||||
|
||||
如果你的 harness 存储了一个 sidecar 绑定，请实现 `reset(...)`，这样 OpenClaw
|
||||
才能在所属 OpenClaw 会话被重置时清除它。
|
||||
如果你的 harness 存储了 sidecar 绑定，请实现 `reset(...)`，以便 OpenClaw 在所属 OpenClaw 会话被重置时可以清除它。
|
||||
|
||||
## 工具与媒体结果
|
||||
|
||||
核心会构建 OpenClaw 工具列表，并将其传入已准备好的尝试。
|
||||
当 harness 执行动态工具调用时，请通过
|
||||
harness 结果结构返回工具结果，而不是自行发送渠道媒体。
|
||||
核心会构造 OpenClaw 工具列表，并将其传入已准备好的尝试中。当 harness 执行动态工具调用时，请通过 harness 结果结构返回工具结果，而不是自行发送渠道媒体。
|
||||
|
||||
这样可以让文本、图片、视频、音乐、TTS、审批以及消息工具输出
|
||||
与基于 PI 的运行保持相同的投递路径。
|
||||
这样可以让文本、图像、视频、音乐、TTS、审批以及消息工具输出，与由 PI 支持的运行使用相同的投递路径。
|
||||
|
||||
## 当前限制
|
||||
|
||||
- 公开导入路径是通用的，但某些尝试/结果类型别名
|
||||
仍然为了兼容而保留 `Pi` 命名。
|
||||
- 第三方 harness 安装仍是实验性的。在你确实需要原生会话运行时之前，
|
||||
优先使用提供商插件。
|
||||
- 支持跨轮次切换 harness。不要在一轮执行过程中，在原生工具、审批、助手文本或消息发送已经开始后
|
||||
再切换 harness。
|
||||
- 公共导入路径是通用的，但某些 attempt/result 类型别名仍然保留 `Pi` 命名以维持兼容性。
|
||||
- 第三方 harness 安装仍是实验性的。在你确实需要原生会话运行时之前，优先使用提供商插件。
|
||||
- 支持跨轮次切换 harness。不要在一个轮次进行到一半时切换 harness，尤其是在原生工具、审批、助手文本或消息发送已经开始之后。
|
||||
|
||||
## 相关
|
||||
## 相关内容
|
||||
|
||||
- [SDK 概览](/zh-CN/plugins/sdk-overview)
|
||||
- [运行时辅助工具](/zh-CN/plugins/sdk-runtime)
|
||||
|
||||
@ -1,59 +1,59 @@
|
||||
---
|
||||
read_when:
|
||||
- 你想在 OpenClaw 中使用 OpenAI 模型
|
||||
- 你想使用 Codex 订阅认证，而不是 API key
|
||||
- 你想使用 Codex 订阅身份验证，而不是 API 密钥
|
||||
- 你需要更严格的 GPT-5 智能体执行行为
|
||||
summary: 在 OpenClaw 中通过 API key 或 Codex 订阅使用 OpenAI
|
||||
summary: 在 OpenClaw 中使用 OpenAI 的 API 密钥或 Codex 订阅
|
||||
title: OpenAI
|
||||
x-i18n:
|
||||
generated_at: "2026-04-23T21:01:16Z"
|
||||
generated_at: "2026-04-23T21:49:31Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 39f5259ef82bb95bb7a94cf36a33c4a3ea2b9ba06f5355dc7abf256167d7a4b9
|
||||
source_hash: 25d8fb540af37366c84380feca3dae43e8b206ff77d6a22af3cdddc1cf0373fc
|
||||
source_path: providers/openai.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
OpenAI 为 GPT 模型提供开发者 API。OpenClaw 在相同的规范 OpenAI 模型引用后支持两种认证路径：
|
||||
OpenAI 为 GPT 模型提供开发者 API。OpenClaw 在同一套规范的 OpenAI 模型引用后支持两种身份验证路径：
|
||||
|
||||
- **API key** —— 直接访问 OpenAI Platform，并按用量计费（`openai/*` 模型）
|
||||
- **Codex 订阅** —— 使用 ChatGPT/Codex 登录与订阅访问。内部认证/provider id 是 `openai-codex`，但新的模型引用仍应使用 `openai/*`。
|
||||
- **API 密钥** — 直接访问 OpenAI Platform，并按使用量计费（`openai/*` 模型）
|
||||
- **Codex 订阅** — 使用 ChatGPT/Codex 登录并通过订阅访问。内部 auth/provider id 为 `openai-codex`，但新的模型引用仍应使用 `openai/*`。
|
||||
|
||||
OpenAI 明确支持在 OpenClaw 这样的外部工具和工作流中使用订阅 OAuth。
|
||||
|
||||
## OpenClaw 功能覆盖
|
||||
## OpenClaw 功能覆盖范围
|
||||
|
||||
| OpenAI 能力 | OpenClaw 界面 | 状态 |
|
||||
| ------------------------- | ----------------------------------------- | ------------------------------------------------------ |
|
||||
| Chat / Responses | `openai/<model>` 模型提供商 | 支持 |
|
||||
| Codex 订阅模型 | 带 `openai-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"` | 支持 |
|
||||
| Embeddings | memory embedding provider | 支持 |
|
||||
| 聊天 / Responses | `openai/<model>` 模型提供商 | 是 |
|
||||
| Codex 订阅模型 | `openai/<model>` 搭配 `openai-codex` 身份验证 | 是 |
|
||||
| 服务端 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"` | 是 |
|
||||
| Embeddings | memory embedding provider | 是 |
|
||||
|
||||
## 入门指南
|
||||
|
||||
请选择你偏好的认证方式，并按照相应步骤进行设置。
|
||||
选择你偏好的身份验证方式，并按照设置步骤进行。
|
||||
|
||||
<Tabs>
|
||||
<Tab title="API key（OpenAI Platform）">
|
||||
**最适合：** 直接 API 访问和按用量计费。
|
||||
<Tab title="API 密钥（OpenAI Platform）">
|
||||
**最适合：** 直接 API 访问和按使用量计费。
|
||||
|
||||
<Steps>
|
||||
<Step title="获取你的 API key">
|
||||
在 [OpenAI Platform dashboard](https://platform.openai.com/api-keys) 中创建或复制一个 API key。
|
||||
<Step title="获取你的 API 密钥">
|
||||
从 [OpenAI Platform 控制台](https://platform.openai.com/api-keys) 创建或复制一个 API 密钥。
|
||||
</Step>
|
||||
<Step title="运行新手引导">
|
||||
```bash
|
||||
openclaw onboard --auth-choice openai-api-key
|
||||
```
|
||||
|
||||
或者直接传入 key：
|
||||
或直接传入密钥：
|
||||
|
||||
```bash
|
||||
openclaw onboard --openai-api-key "$OPENAI_API_KEY"
|
||||
@ -66,15 +66,15 @@ OpenAI 明确支持在 OpenClaw 这样的外部工具和工作流中使用订阅
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
### 路由摘要
|
||||
### 路径摘要
|
||||
|
||||
| 模型引用 | 路由 | 认证 |
|
||||
| 模型引用 | 路径 | 身份验证 |
|
||||
|-----------|-------|------|
|
||||
| `openai/gpt-5.5` | 直接 OpenAI Platform API | `OPENAI_API_KEY` |
|
||||
| `openai/gpt-5.5-pro` | 直接 OpenAI Platform API | `OPENAI_API_KEY` |
|
||||
|
||||
<Note>
|
||||
`openai-codex/*` 仍然作为旧版兼容别名被接受，但新配置应使用 `openai/*`。
|
||||
`openai-codex/*` 仍可作为旧版兼容别名使用，但新的配置应使用 `openai/*`。
|
||||
</Note>
|
||||
|
||||
### 配置示例
|
||||
@ -87,13 +87,13 @@ OpenAI 明确支持在 OpenClaw 这样的外部工具和工作流中使用订阅
|
||||
```
|
||||
|
||||
<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 key。Codex 云需要 ChatGPT 登录。
|
||||
**最适合：** 使用你的 ChatGPT/Codex 订阅，而不是单独的 API 密钥。Codex cloud 需要 ChatGPT 登录。
|
||||
|
||||
<Steps>
|
||||
<Step title="运行 Codex OAuth">
|
||||
@ -107,7 +107,7 @@ OpenAI 明确支持在 OpenClaw 这样的外部工具和工作流中使用订阅
|
||||
openclaw models auth login --provider openai-codex
|
||||
```
|
||||
|
||||
对于无头或不适合 localhost 回调的设置，请添加 `--device-code`，通过 ChatGPT 设备码流程登录，而不是使用 localhost 浏览器回调：
|
||||
对于无头环境或不适合回调的设置，可以添加 `--device-code`，通过 ChatGPT 设备码流程登录，而不是使用 localhost 浏览器回调：
|
||||
|
||||
```bash
|
||||
openclaw models auth login --provider openai-codex --device-code
|
||||
@ -125,14 +125,14 @@ OpenAI 明确支持在 OpenClaw 这样的外部工具和工作流中使用订阅
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
### 路由摘要
|
||||
### 路径摘要
|
||||
|
||||
| 模型引用 | 路由 | 认证 |
|
||||
| 模型引用 | 路径 | 身份验证 |
|
||||
|-----------|-------|------|
|
||||
| `openai/gpt-5.5` | ChatGPT/Codex OAuth | Codex 登录 |
|
||||
|
||||
<Note>
|
||||
`openai-codex/*` 和 `codex/*` 模型引用是旧版兼容别名。对于认证/profile 命令，请继续使用 `openai-codex` provider id。
|
||||
`openai-codex/*` 和 `codex/*` 模型引用是旧版兼容别名。对于身份验证/配置文件命令，请继续使用 `openai-codex` provider id。
|
||||
</Note>
|
||||
|
||||
### 配置示例
|
||||
@ -144,24 +144,28 @@ OpenAI 明确支持在 OpenClaw 这样的外部工具和工作流中使用订阅
|
||||
```
|
||||
|
||||
<Note>
|
||||
新手引导不再从 `~/.codex` 导入 OAuth 材料。请使用浏览器 OAuth（默认）或上述设备码流程登录——OpenClaw 会在自己的智能体认证存储中管理得到的凭证。
|
||||
新手引导不再从 `~/.codex` 导入 OAuth 材料。请使用浏览器 OAuth（默认）或上述设备码流程登录——OpenClaw 会在自己的智能体身份验证存储中管理生成的凭证。
|
||||
</Note>
|
||||
|
||||
### 状态指示器
|
||||
|
||||
聊天 `/status` 会显示当前会话使用的是哪个内置 harness。默认 PI harness 显示为 `Runner: pi (embedded)`，不会添加额外徽章。当选择的是内置 Codex app-server harness 时，`/status` 会在 `Fast` 后附加非 PI harness id，例如
|
||||
`Fast · codex`。现有会话会保留其已记录的 harness id，因此如果你更改了 `embeddedHarness`，并希望 `/status` 反映新的 PI/Codex 选择，请使用 `/new` 或 `/reset`。
|
||||
聊天 `/status` 会显示当前
|
||||
会话正在使用哪个嵌入式 harness。默认的 PI harness 显示为 `Runner: pi (embedded)`，并且
|
||||
不会添加单独的标记。当选择内置的 Codex app-server harness 时，
|
||||
`/status` 会在 `Fast` 后附加非 PI harness id，例如
|
||||
`Fast · codex`。现有会话会保留其记录的 harness id，因此如果你在更改 `embeddedHarness` 后希望 `/status`
|
||||
反映新的 PI/Codex 选择，请使用 `/new` 或 `/reset`。
|
||||
|
||||
### 上下文窗口上限
|
||||
|
||||
OpenClaw 将模型元数据与运行时上下文上限视为两个独立值。
|
||||
OpenClaw 将模型元数据和运行时上下文上限视为两个独立的值。
|
||||
|
||||
对于通过 Codex OAuth 使用的 `openai/gpt-5.5`：
|
||||
|
||||
- 原生 `contextWindow`：`1000000`
|
||||
- 默认运行时 `contextTokens` 上限：`272000`
|
||||
|
||||
这个较小的默认上限在实践中具有更好的延迟和质量特性。你可以通过 `contextTokens` 覆盖它：
|
||||
实际使用中，较小的默认上限通常具有更好的延迟和质量表现。你可以使用 `contextTokens` 进行覆盖：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -176,7 +180,7 @@ OpenAI 明确支持在 OpenClaw 这样的外部工具和工作流中使用订阅
|
||||
```
|
||||
|
||||
<Note>
|
||||
请使用 `contextWindow` 声明原生模型元数据。请使用 `contextTokens` 限制运行时上下文预算。
|
||||
使用 `contextWindow` 声明原生模型元数据。使用 `contextTokens` 限制运行时上下文预算。
|
||||
</Note>
|
||||
|
||||
</Tab>
|
||||
@ -184,15 +188,18 @@ OpenAI 明确支持在 OpenClaw 这样的外部工具和工作流中使用订阅
|
||||
|
||||
## 图像生成
|
||||
|
||||
内置 `openai` 插件通过 `image_generate` 工具注册图像生成能力。
|
||||
内置的 `openai` 插件通过 `image_generate` 工具注册图像生成功能。
|
||||
它通过同一个 `openai/gpt-image-2` 模型引用，同时支持基于 OpenAI API 密钥的图像生成和基于 Codex OAuth 的图像生成。
|
||||
|
||||
| 能力 | 值 |
|
||||
| ------------------------- | ---------------------------------- |
|
||||
| 默认模型 | `openai/gpt-image-2` |
|
||||
| 每次请求最大图像数 | 4 |
|
||||
| 编辑模式 | 启用（最多 5 张参考图） |
|
||||
| 尺寸覆盖 | 支持，包括 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
|
||||
{
|
||||
@ -205,43 +212,36 @@ OpenAI 明确支持在 OpenClaw 这样的外部工具和工作流中使用订阅
|
||||
```
|
||||
|
||||
<Note>
|
||||
共享工具参数、provider 选择和故障转移行为请参阅[图像生成](/zh-CN/tools/image-generation)。
|
||||
参见 [Image Generation](/zh-CN/tools/image-generation)，了解共享工具参数、provider 选择和故障切换行为。
|
||||
</Note>
|
||||
|
||||
`gpt-image-2` 是 OpenAI 文生图和图像编辑的默认模型。
|
||||
`gpt-image-1` 仍可作为显式模型覆盖使用，但新的 OpenAI 图像工作流应使用 `openai/gpt-image-2`。
|
||||
`gpt-image-2` 是 OpenAI 文生图和图像编辑的默认模型。`gpt-image-1` 仍可作为显式模型覆盖使用，但新的 OpenAI 图像工作流应使用 `openai/gpt-image-2`。
|
||||
|
||||
`openai-codex` provider 也会通过 OpenAI Codex OAuth 为图像生成和参考图像编辑暴露 `gpt-image-2`。
|
||||
当智能体已通过 Codex OAuth 登录、但没有 `OPENAI_API_KEY` 时，请使用
|
||||
`openai-codex/gpt-image-2`。
|
||||
对于 Codex OAuth 安装，请继续使用相同的 `openai/gpt-image-2` 引用。如果没有
|
||||
`OPENAI_API_KEY`，OpenClaw 会解析为 `openai-codex` auth profile 存储的 OAuth 访问令牌，
|
||||
并通过 Codex Responses 后端发送图像请求，因此这一路径无需公开的 OpenAI Images API 密钥也可使用。
|
||||
|
||||
生成：
|
||||
|
||||
```
|
||||
/tool image_generate model=openai/gpt-image-2 prompt="A polished launch poster for OpenClaw on macOS" size=3840x2160 count=1
|
||||
```
|
||||
|
||||
使用 Codex OAuth 生成：
|
||||
|
||||
```
|
||||
/tool image_generate model=openai-codex/gpt-image-2 prompt="A polished launch poster for OpenClaw on macOS" size=3840x2160 count=1
|
||||
/tool image_generate model=openai/gpt-image-2 prompt="为 macOS 上的 OpenClaw 制作一张精美的发布海报" size=3840x2160 count=1
|
||||
```
|
||||
|
||||
编辑：
|
||||
|
||||
```
|
||||
/tool image_generate model=openai/gpt-image-2 prompt="Preserve the object shape, change the material to translucent glass" image=/path/to/reference.png size=1024x1536
|
||||
/tool image_generate model=openai/gpt-image-2 prompt="保留物体形状，将材质改为半透明玻璃" image=/path/to/reference.png size=1024x1536
|
||||
```
|
||||
|
||||
## 视频生成
|
||||
|
||||
内置 `openai` 插件通过 `video_generate` 工具注册视频生成能力。
|
||||
内置的 `openai` 插件通过 `video_generate` 工具注册视频生成功能。
|
||||
|
||||
| 能力 | 值 |
|
||||
| ---------------- | --------------------------------------------------------------------------------- |
|
||||
| 默认模型 | `openai/sora-2` |
|
||||
| 模式 | 文生视频、图生视频、单视频编辑 |
|
||||
| 参考输入 | 1 张图片或 1 个视频 |
|
||||
| 参考输入 | 1 张图像或 1 个视频 |
|
||||
| 尺寸覆盖 | 支持 |
|
||||
| 其他覆盖 | `aspectRatio`、`resolution`、`audio`、`watermark` 会被忽略，并给出工具警告 |
|
||||
|
||||
@ -256,20 +256,20 @@ OpenAI 明确支持在 OpenClaw 这样的外部工具和工作流中使用订阅
|
||||
```
|
||||
|
||||
<Note>
|
||||
共享工具参数、provider 选择和故障转移行为请参阅[视频生成](/zh-CN/tools/video-generation)。
|
||||
参见 [Video Generation](/zh-CN/tools/video-generation)，了解共享工具参数、provider 选择和故障切换行为。
|
||||
</Note>
|
||||
|
||||
## GPT-5 提示词贡献
|
||||
|
||||
OpenClaw 会为跨 provider 的 GPT-5 家族运行添加一个共享 GPT-5 提示词贡献。它按模型 id 应用，因此 `openai/gpt-5.5`、`openrouter/openai/gpt-5.5`、`opencode/gpt-5.5` 以及其他兼容的 GPT-5 引用都会收到相同的覆盖层。较旧的 GPT-4.x 模型则不会。
|
||||
OpenClaw 会为跨 provider 的 GPT-5 系列运行添加共享的 GPT-5 提示词贡献。它按模型 id 生效，因此 `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 行为和心跳覆盖，因此当 `openai/gpt-5.x` 会话被强制使用 `embeddedHarness.runtime: "codex"` 时，也会保留相同的执行跟进和主动心跳指导，即使 Codex 拥有该 harness 提示词的其余部分。
|
||||
内置的原生 Codex harness 通过 Codex app-server 开发者指令使用相同的 GPT-5 行为和心跳覆盖层，因此即使其余 harness 提示词由 Codex 接管，强制通过 `embeddedHarness.runtime: "codex"` 运行的 `openai/gpt-5.x` 会话仍会保留相同的后续执行和主动心跳指导。
|
||||
|
||||
GPT-5 提示词贡献增加了一个带标签的行为契约，用于人格保持、执行安全、工具纪律、输出形状、完成检查和验证。渠道专用的回复和静默消息行为则仍保留在共享 OpenClaw system prompt 和出站投递策略中。GPT-5 指导会始终为匹配模型启用。友好交互风格层是独立的，并且可配置。
|
||||
GPT-5 贡献为人格持续性、执行安全、工具纪律、输出结构、完成检查和验证添加了带标签的行为契约。特定渠道的回复和静默消息行为仍保留在共享的 OpenClaw 系统提示词和出站传递策略中。对于匹配的模型，GPT-5 指导始终启用。友好的交互风格层是独立且可配置的。
|
||||
|
||||
| 值 | 效果 |
|
||||
| ---------------------- | ------------------------------------------- |
|
||||
| `"friendly"`（默认） | 启用友好交互风格层 |
|
||||
| `"friendly"`（默认） | 启用友好的交互风格层 |
|
||||
| `"on"` | `"friendly"` 的别名 |
|
||||
| `"off"` | 仅禁用友好风格层 |
|
||||
|
||||
@ -295,30 +295,30 @@ GPT-5 提示词贡献增加了一个带标签的行为契约，用于人格保
|
||||
</Tabs>
|
||||
|
||||
<Tip>
|
||||
运行时值不区分大小写，因此 `"Off"` 和 `"off"` 都会禁用友好风格层。
|
||||
这些值在运行时不区分大小写，因此 `"Off"` 和 `"off"` 都会禁用友好风格层。
|
||||
</Tip>
|
||||
|
||||
<Note>
|
||||
当未设置共享的 `agents.defaults.promptOverlays.gpt5.personality` 时，仍会读取旧版 `plugins.entries.openai.config.personality` 作为兼容回退。
|
||||
旧版 `plugins.entries.openai.config.personality` 仍会作为兼容性回退项读取，当未设置共享的 `agents.defaults.promptOverlays.gpt5.personality` 配置时会使用它。
|
||||
</Note>
|
||||
|
||||
## 语音和语音处理
|
||||
## 语音与音频
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="语音合成（TTS）">
|
||||
内置 `openai` 插件会为 `messages.tts` 界面注册语音合成能力。
|
||||
内置的 `openai` 插件为 `messages.tts` 界面注册了语音合成功能。
|
||||
|
||||
| 设置 | 配置路径 | 默认值 |
|
||||
|---------|------------|---------|
|
||||
| 模型 | `messages.tts.providers.openai.model` | `gpt-4o-mini-tts` |
|
||||
| 语音 | `messages.tts.providers.openai.voice` | `coral` |
|
||||
| 速度 | `messages.tts.providers.openai.speed` | （未设置） |
|
||||
| 音色 | `messages.tts.providers.openai.voice` | `coral` |
|
||||
| 语速 | `messages.tts.providers.openai.speed` | （未设置） |
|
||||
| 指令 | `messages.tts.providers.openai.instructions` | （未设置，仅 `gpt-4o-mini-tts` 支持） |
|
||||
| 格式 | `messages.tts.providers.openai.responseFormat` | 语音便签为 `opus`，文件为 `mp3` |
|
||||
| API key | `messages.tts.providers.openai.apiKey` | 回退到 `OPENAI_API_KEY` |
|
||||
| 格式 | `messages.tts.providers.openai.responseFormat` | 语音便笺为 `opus`，文件为 `mp3` |
|
||||
| API 密钥 | `messages.tts.providers.openai.apiKey` | 回退到 `OPENAI_API_KEY` |
|
||||
| Base URL | `messages.tts.providers.openai.baseUrl` | `https://api.openai.com/v1` |
|
||||
|
||||
可用模型：`gpt-4o-mini-tts`、`tts-1`、`tts-1-hd`。可用语音：`alloy`、`ash`、`ballad`、`cedar`、`coral`、`echo`、`fable`、`juniper`、`marin`、`onyx`、`nova`、`sage`、`shimmer`、`verse`。
|
||||
可用模型：`gpt-4o-mini-tts`、`tts-1`、`tts-1-hd`。可用音色：`alloy`、`ash`、`ballad`、`cedar`、`coral`、`echo`、`fable`、`juniper`、`marin`、`onyx`、`nova`、`sage`、`shimmer`、`verse`。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -333,22 +333,23 @@ GPT-5 提示词贡献增加了一个带标签的行为契约，用于人格保
|
||||
```
|
||||
|
||||
<Note>
|
||||
设置 `OPENAI_TTS_BASE_URL` 可覆盖 TTS 的 base URL，而不会影响聊天 API 端点。
|
||||
设置 `OPENAI_TTS_BASE_URL` 可覆盖 TTS Base URL，而不会影响聊天 API 端点。
|
||||
</Note>
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="语音转文本">
|
||||
内置 `openai` 插件会通过
|
||||
OpenClaw 的媒体理解转写界面注册批量语音转文本能力。
|
||||
内置的 `openai` 插件通过
|
||||
OpenClaw 的媒体理解转录界面注册了批量语音转文本功能。
|
||||
|
||||
- 默认模型：`gpt-4o-transcribe`
|
||||
- 端点：OpenAI REST `/v1/audio/transcriptions`
|
||||
- 输入路径：multipart 音频文件上传
|
||||
- 在 OpenClaw 中，凡是入站音频转写使用
|
||||
`tools.media.audio` 的地方都支持它，包括 Discord 语音频道片段和渠道音频附件
|
||||
- 在 OpenClaw 中，只要入站音频转录使用
|
||||
`tools.media.audio`，就支持该功能，包括 Discord 语音频道片段和渠道
|
||||
音频附件
|
||||
|
||||
若要强制对入站音频转写使用 OpenAI：
|
||||
要强制对入站音频转录使用 OpenAI：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -368,12 +369,13 @@ GPT-5 提示词贡献增加了一个带标签的行为契约，用于人格保
|
||||
}
|
||||
```
|
||||
|
||||
当共享音频媒体配置或单次转写请求提供语言和提示词提示时，这些提示会转发给 OpenAI。
|
||||
当由共享音频媒体配置或按次转录请求提供语言和提示词时，
|
||||
这些提示会转发给 OpenAI。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="实时转录">
|
||||
内置 `openai` 插件会为 Voice Call 插件注册实时转录能力。
|
||||
内置的 `openai` 插件为 Voice Call 插件注册了实时转录功能。
|
||||
|
||||
| 设置 | 配置路径 | 默认值 |
|
||||
|---------|------------|---------|
|
||||
@ -382,25 +384,25 @@ GPT-5 提示词贡献增加了一个带标签的行为契约，用于人格保
|
||||
| 提示词 | `...openai.prompt` | （未设置） |
|
||||
| 静音时长 | `...openai.silenceDurationMs` | `800` |
|
||||
| VAD 阈值 | `...openai.vadThreshold` | `0.5` |
|
||||
| API key | `...openai.apiKey` | 回退到 `OPENAI_API_KEY` |
|
||||
| API 密钥 | `...openai.apiKey` | 回退到 `OPENAI_API_KEY` |
|
||||
|
||||
<Note>
|
||||
它使用 WebSocket 连接到 `wss://api.openai.com/v1/realtime`，并采用 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`）。此流式 provider 用于 Voice Call 的实时转录路径；Discord 语音当前仍会录制短片段，并改用批量 `tools.media.audio` 转录路径。
|
||||
</Note>
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="实时语音">
|
||||
内置 `openai` 插件会为 Voice Call 插件注册实时语音能力。
|
||||
内置的 `openai` 插件为 Voice Call 插件注册了实时语音功能。
|
||||
|
||||
| 设置 | 配置路径 | 默认值 |
|
||||
|---------|------------|---------|
|
||||
| 模型 | `plugins.entries.voice-call.config.realtime.providers.openai.model` | `gpt-realtime-1.5` |
|
||||
| 语音 | `...openai.voice` | `alloy` |
|
||||
| 音色 | `...openai.voice` | `alloy` |
|
||||
| Temperature | `...openai.temperature` | `0.8` |
|
||||
| VAD 阈值 | `...openai.vadThreshold` | `0.5` |
|
||||
| 静音时长 | `...openai.silenceDurationMs` | `500` |
|
||||
| API key | `...openai.apiKey` | 回退到 `OPENAI_API_KEY` |
|
||||
| API 密钥 | `...openai.apiKey` | 回退到 `OPENAI_API_KEY` |
|
||||
|
||||
<Note>
|
||||
通过 `azureEndpoint` 和 `azureDeployment` 配置键支持 Azure OpenAI。支持双向工具调用。使用 G.711 u-law 音频格式。
|
||||
@ -411,24 +413,29 @@ GPT-5 提示词贡献增加了一个带标签的行为契约，用于人格保
|
||||
|
||||
## 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) 下 **实时语音** 手风琴部分。
|
||||
（`plugins.entries.voice-call.config.realtime.providers.openai.azureEndpoint`），
|
||||
不受 `models.providers.openai.baseUrl` 影响。有关其实时语音的 Azure
|
||||
设置，请参见 [语音与音频](#voice-and-speech) 下的 **实时语音**
|
||||
折叠面板。
|
||||
</Note>
|
||||
|
||||
在以下情况下使用 Azure OpenAI：
|
||||
以下情况适合使用 Azure OpenAI：
|
||||
|
||||
- 你已经拥有 Azure OpenAI 订阅、配额或企业协议
|
||||
- 你需要 Azure 提供的区域数据驻留或合规控制
|
||||
- 你希望将流量保留在现有 Azure 租户内部
|
||||
- 你希望将流量保留在现有的 Azure 租户内
|
||||
|
||||
### 配置
|
||||
|
||||
若要通过内置 `openai` provider 使用 Azure 进行图像生成，请将
|
||||
若要通过内置 `openai` provider 使用 Azure 图像生成，请将
|
||||
`models.providers.openai.baseUrl` 指向你的 Azure 资源，并将 `apiKey` 设置为
|
||||
Azure OpenAI key（而不是 OpenAI Platform key）：
|
||||
Azure OpenAI 密钥（而非 OpenAI Platform 密钥）：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -443,92 +450,96 @@ Azure OpenAI key（而不是 OpenAI Platform key）：
|
||||
}
|
||||
```
|
||||
|
||||
OpenClaw 会识别以下 Azure 主机后缀，并将其用于 Azure 图像生成路由：
|
||||
OpenClaw 会为 Azure 图像生成
|
||||
路径识别以下 Azure 主机后缀：
|
||||
|
||||
- `*.openai.azure.com`
|
||||
- `*.services.ai.azure.com`
|
||||
- `*.cognitiveservices.azure.com`
|
||||
|
||||
对于识别出的 Azure 主机上的图像生成请求，OpenClaw 会：
|
||||
对于发送到已识别 Azure 主机的图像生成请求，OpenClaw 会：
|
||||
|
||||
- 发送 `api-key` 标头，而不是 `Authorization: Bearer`
|
||||
- 使用部署作用域路径（`/openai/deployments/{deployment}/...`）
|
||||
- 在每个请求后追加 `?api-version=...`
|
||||
- 发送 `api-key` 请求头，而不是 `Authorization: Bearer`
|
||||
- 使用以部署为范围的路径（`/openai/deployments/{deployment}/...`）
|
||||
- 为每个请求附加 `?api-version=...`
|
||||
|
||||
其他 base URL（公共 OpenAI、兼容 OpenAI 的代理）仍使用标准
|
||||
OpenAI 图像请求形状。
|
||||
其他 base URL（公共 OpenAI、兼容 OpenAI 的代理）将继续使用标准
|
||||
OpenAI 图像请求格式。
|
||||
|
||||
<Note>
|
||||
`openai` provider 的图像生成路径使用 Azure 路由功能，要求
|
||||
OpenClaw 版本为 2026.4.22 或更高。更早版本会将任意自定义
|
||||
`openai.baseUrl` 视为公共 OpenAI 端点，并在 Azure 图像部署上失败。
|
||||
`openai` provider 的图像生成路径的 Azure 路由要求
|
||||
OpenClaw 2026.4.22 或更高版本。更早版本会将任何自定义
|
||||
`openai.baseUrl` 视为公共 OpenAI 端点，因此在 Azure
|
||||
图像部署上会失败。
|
||||
</Note>
|
||||
|
||||
### API 版本
|
||||
### API 版本
|
||||
|
||||
设置 `AZURE_OPENAI_API_VERSION` 可为
|
||||
Azure 图像生成路径固定特定的 Azure 预览版或 GA 版本：
|
||||
设置 `AZURE_OPENAI_API_VERSION` 以为 Azure 图像生成路径固定特定的 Azure 预览版或 GA 版本：
|
||||
|
||||
```bash
|
||||
export AZURE_OPENAI_API_VERSION="2024-12-01-preview"
|
||||
```
|
||||
```bash
|
||||
export AZURE_OPENAI_API_VERSION="2024-12-01-preview"
|
||||
```
|
||||
|
||||
当该变量未设置时，默认值为 `2024-12-01-preview`。
|
||||
|
||||
### 模型名称即部署名称
|
||||
### 模型名称就是部署名称
|
||||
|
||||
Azure OpenAI 会将模型绑定到部署。对于通过内置 `openai` provider 路由的 Azure 图像生成请求，OpenClaw 中的 `model` 字段必须是你在 Azure 门户中配置的**Azure 部署名称**，而不是公共 OpenAI 模型 id。
|
||||
Azure OpenAI 将模型绑定到部署。对于通过内置 `openai` provider 路由的 Azure 图像生成请求，OpenClaw 中的 `model` 字段
|
||||
必须是你在 Azure 门户中配置的**Azure 部署名称**，而不是公共 OpenAI 模型 id。
|
||||
|
||||
如果你创建了一个名为 `gpt-image-2-prod` 的部署，并让它提供 `gpt-image-2`：
|
||||
如果你创建了一个名为 `gpt-image-2-prod` 的部署来提供 `gpt-image-2`：
|
||||
|
||||
```
|
||||
/tool image_generate model=openai/gpt-image-2-prod prompt="A clean poster" size=1024x1024 count=1
|
||||
/tool image_generate model=openai/gpt-image-2-prod prompt="一张简洁的海报" size=1024x1024 count=1
|
||||
```
|
||||
|
||||
同样的部署名称规则也适用于通过内置 `openai` provider 路由的图像生成调用。
|
||||
|
||||
### 区域可用性
|
||||
|
||||
Azure 图像生成当前仅在部分区域可用
|
||||
Azure 图像生成目前仅在部分区域可用
|
||||
（例如 `eastus2`、`swedencentral`、`polandcentral`、`westus3`、
|
||||
`uaenorth`）。在创建部署之前，请先检查 Microsoft 当前的
|
||||
区域列表，并确认你的区域提供了对应模型。
|
||||
`uaenorth`）。在创建部署之前，请先查看 Microsoft 最新的区域列表，
|
||||
并确认你的区域提供了特定模型。
|
||||
|
||||
### 参数差异
|
||||
|
||||
Azure OpenAI 和公共 OpenAI 并不总是接受相同的图像参数。
|
||||
Azure 可能会拒绝公共 OpenAI 可接受的某些选项（例如在 `gpt-image-2` 上某些
|
||||
`background` 值），或者只在特定模型版本中暴露这些选项。这些差异来自 Azure 和底层模型，而不是 OpenClaw。如果 Azure 请求因校验错误而失败，请检查 Azure 门户中你的具体部署和 API 版本所支持的参数集。
|
||||
Azure OpenAI 与公共 OpenAI 并不总是接受相同的图像参数。
|
||||
Azure 可能会拒绝公共 OpenAI 允许的选项（例如 `gpt-image-2` 上的某些
|
||||
`background` 值），或者仅在特定模型版本中提供这些选项。这些差异来自 Azure 和底层模型，而不是
|
||||
OpenClaw。如果 Azure 请求因验证错误而失败，请在
|
||||
Azure 门户中检查你的特定部署和 API 版本所支持的参数集。
|
||||
|
||||
<Note>
|
||||
Azure OpenAI 使用原生传输和兼容行为，但不会接收
|
||||
OpenClaw 的隐藏归因标头——请参阅[高级配置](#advanced-configuration)下
|
||||
**原生与兼容 OpenAI 路由** 手风琴部分。
|
||||
OpenClaw 的隐藏归因请求头——参见 [Advanced configuration](#advanced-configuration) 下 **原生路由与 OpenAI 兼容路由**
|
||||
折叠面板。
|
||||
|
||||
对于 Azure 上的聊天或 Responses 流量（超出图像生成范围），请使用
|
||||
新手引导流程或专门的 Azure provider 配置——仅设置 `openai.baseUrl`
|
||||
并不会自动启用 Azure 的 API/认证形状。还存在一个独立的
|
||||
`azure-openai-responses/*` provider；请参阅下方
|
||||
Server-side compaction 手风琴部分。
|
||||
对于 Azure 上的聊天或 Responses 流量（图像生成之外），请使用
|
||||
新手引导流程或专用的 Azure provider 配置——仅设置 `openai.baseUrl`
|
||||
不会自动采用 Azure 的 API/身份验证格式。存在一个单独的
|
||||
`azure-openai-responses/*` provider；请参见下方的
|
||||
服务端压缩折叠面板。
|
||||
</Note>
|
||||
|
||||
## 高级配置
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="传输（WebSocket vs SSE）">
|
||||
OpenClaw 对 `openai/*` 和 `openai-codex/*` 都默认使用 WebSocket 优先并回退到 SSE（`"auto"`）。
|
||||
<Accordion title="传输（WebSocket 与 SSE）">
|
||||
对于 `openai/*` 和 `openai-codex/*`，OpenClaw 都采用 WebSocket 优先并在失败时回退到 SSE（`"auto"`）。
|
||||
|
||||
在 `"auto"` 模式下，OpenClaw 会：
|
||||
- 对一次早期 WebSocket 失败重试一次，然后回退到 SSE
|
||||
- 失败后，将 WebSocket 标记为约 60 秒降级，并在冷却期间使用 SSE
|
||||
- 在回退到 SSE 之前，重试一次早期 WebSocket 失败
|
||||
- 发生失败后，将 WebSocket 标记为降级约 60 秒，并在冷却期间使用 SSE
|
||||
- 为重试和重连附加稳定的会话与轮次身份标头
|
||||
- 跨不同传输变体统一用量计数器（`input_tokens` / `prompt_tokens`）
|
||||
- 在不同传输变体之间规范化使用量计数器（`input_tokens` / `prompt_tokens`）
|
||||
|
||||
| 值 | 行为 |
|
||||
|-------|----------|
|
||||
| `"auto"`（默认） | WebSocket 优先，SSE 回退 |
|
||||
| `"sse"` | 强制仅使用 SSE |
|
||||
| `"websocket"` | 强制仅使用 WebSocket |
|
||||
| `"auto"`（默认） | WebSocket 优先，失败时回退到 SSE |
|
||||
| `"sse"` | 仅强制使用 SSE |
|
||||
| `"websocket"` | 仅强制使用 WebSocket |
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -551,7 +562,7 @@ export AZURE_OPENAI_API_VERSION="2024-12-01-preview"
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="WebSocket 预热">
|
||||
OpenClaw 默认会为 `openai/*` 启用 WebSocket 预热，以减少首轮延迟。
|
||||
OpenClaw 默认对 `openai/*` 启用 WebSocket 预热，以减少首轮延迟。
|
||||
|
||||
```json5
|
||||
// 禁用预热
|
||||
@ -570,13 +581,13 @@ export AZURE_OPENAI_API_VERSION="2024-12-01-preview"
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Fast mode">
|
||||
OpenClaw 为 `openai/*` 暴露了一个共享 fast mode 开关：
|
||||
<Accordion title="快速模式">
|
||||
OpenClaw 为 `openai/*` 提供共享的快速模式切换：
|
||||
|
||||
- **聊天/UI：** `/fast status|on|off`
|
||||
- **配置：** `agents.defaults.models["<provider>/<model>"].params.fastMode`
|
||||
|
||||
启用后，OpenClaw 会将 fast mode 映射为 OpenAI priority processing（`service_tier = "priority"`）。已有的 `service_tier` 值会被保留，fast mode 不会重写 `reasoning` 或 `text.verbosity`。
|
||||
启用后，OpenClaw 会将快速模式映射为 OpenAI 优先处理（`service_tier = "priority"`）。现有的 `service_tier` 值会被保留，快速模式不会重写 `reasoning` 或 `text.verbosity`。
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -591,13 +602,13 @@ export AZURE_OPENAI_API_VERSION="2024-12-01-preview"
|
||||
```
|
||||
|
||||
<Note>
|
||||
会话覆盖优先于配置。在 Sessions UI 中清除会话覆盖后，会话会回到配置中的默认值。
|
||||
会话级覆盖优先于配置。在 Sessions UI 中清除会话覆盖后，会话将恢复为配置的默认值。
|
||||
</Note>
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="优先级处理（service_tier）">
|
||||
OpenAI 的 API 通过 `service_tier` 暴露优先级处理能力。你可以在 OpenClaw 中按模型设置它：
|
||||
<Accordion title="优先处理（service_tier）">
|
||||
OpenAI 的 API 通过 `service_tier` 提供优先处理。你可以在 OpenClaw 中按模型设置它：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -614,21 +625,21 @@ export AZURE_OPENAI_API_VERSION="2024-12-01-preview"
|
||||
支持的值：`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="Server-side compaction（Responses API）">
|
||||
对于直接的 OpenAI Responses 模型（位于 `api.openai.com` 上的 `openai/*`），OpenClaw 会自动启用 server-side compaction：
|
||||
<Accordion title="服务端压缩（Responses API）">
|
||||
对于直接的 OpenAI Responses 模型（位于 `api.openai.com` 的 `openai/*`），OpenClaw 会自动启用服务端压缩：
|
||||
|
||||
- 强制设置 `store: true`（除非模型兼容性设置 `supportsStore: false`）
|
||||
- 强制设置 `store: true`（除非模型兼容性将 `supportsStore` 设为 `false`）
|
||||
- 注入 `context_management: [{ type: "compaction", compact_threshold: ... }]`
|
||||
- 默认 `compact_threshold`：`contextWindow` 的 70%（若不可用则为 `80000`）
|
||||
- 默认 `compact_threshold`：`contextWindow` 的 70%（不可用时为 `80000`）
|
||||
|
||||
<Tabs>
|
||||
<Tab title="显式启用">
|
||||
对于像 Azure OpenAI Responses 这样的兼容端点很有用：
|
||||
适用于 Azure OpenAI Responses 等兼容端点：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -680,13 +691,13 @@ export AZURE_OPENAI_API_VERSION="2024-12-01-preview"
|
||||
</Tabs>
|
||||
|
||||
<Note>
|
||||
`responsesServerCompaction` 只控制 `context_management` 注入。直接的 OpenAI Responses 模型仍会强制 `store: true`，除非兼容性设置了 `supportsStore: false`。
|
||||
`responsesServerCompaction` 仅控制 `context_management` 注入。直接 OpenAI Responses 模型仍会强制使用 `store: true`，除非兼容性将 `supportsStore` 设为 `false`。
|
||||
</Note>
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Strict-agentic GPT 模式">
|
||||
对于 `openai/*` 上的 GPT-5 家族运行，OpenClaw 可使用更严格的内置执行契约：
|
||||
<Accordion title="严格智能体 GPT 模式">
|
||||
对于 `openai/*` 上的 GPT-5 系列运行，OpenClaw 可以使用更严格的嵌入式执行契约：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -698,33 +709,33 @@ export AZURE_OPENAI_API_VERSION="2024-12-01-preview"
|
||||
}
|
||||
```
|
||||
|
||||
启用 `strict-agentic` 后，OpenClaw 会：
|
||||
- 当存在可用工具动作时，不再将仅有规划的轮次视为成功进展
|
||||
- 使用一个立即行动的 steer 重试该轮次
|
||||
- 对于较大工作量自动启用 `update_plan`
|
||||
- 如果模型持续规划却不行动，则显式呈现 blocked 状态
|
||||
使用 `strict-agentic` 时，OpenClaw 会：
|
||||
- 当存在可用工具操作时，不再将仅有计划的轮次视为成功进展
|
||||
- 使用“立即行动”的引导重试该轮次
|
||||
- 对于较大工作自动启用 `update_plan`
|
||||
- 如果模型持续规划而不执行操作，则明确显示阻塞状态
|
||||
|
||||
<Note>
|
||||
仅作用于 OpenAI 和 Codex 的 GPT-5 家族运行。其他提供商和较旧模型家族仍保持默认行为。
|
||||
仅适用于 OpenAI 和 Codex 的 GPT-5 系列运行。其他 provider 和较旧的模型系列保持默认行为。
|
||||
</Note>
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="原生与兼容 OpenAI 路由">
|
||||
OpenClaw 会将直接 OpenAI、Codex 和 Azure OpenAI 端点与通用的兼容 OpenAI `/v1` 代理区别对待：
|
||||
<Accordion title="原生路由与 OpenAI 兼容路由">
|
||||
OpenClaw 会区别对待直接 OpenAI、Codex 和 Azure OpenAI 端点，以及通用的 OpenAI 兼容 `/v1` 代理：
|
||||
|
||||
**原生路由**（`openai/*`、Azure OpenAI）：
|
||||
- 仅对支持 OpenAI `none` effort 的模型保留 `reasoning: { effort: "none" }`
|
||||
- 对于会拒绝 `reasoning.effort: "none"` 的模型或代理，省略禁用 reasoning 的设置
|
||||
- 对于拒绝 `reasoning.effort: "none"` 的模型或代理，省略禁用的 reasoning
|
||||
- 默认将工具 schema 设为严格模式
|
||||
- 仅在已验证的原生主机上附加隐藏归因标头
|
||||
- 保留 OpenAI 专属请求整形（`service_tier`、`store`、reasoning 兼容性、提示词缓存提示）
|
||||
- 仅在已验证的原生主机上附加隐藏归因请求头
|
||||
- 保留 OpenAI 专用的请求格式（`service_tier`、`store`、reasoning 兼容性、提示词缓存提示）
|
||||
|
||||
**代理/兼容路由：**
|
||||
- 使用更宽松的兼容行为
|
||||
- 不会强制严格工具 schema，也不会添加原生专属标头
|
||||
- 不强制严格工具 schema 或原生专用请求头
|
||||
|
||||
Azure OpenAI 使用原生传输和兼容行为，但不会接收隐藏归因标头。
|
||||
Azure OpenAI 使用原生传输和兼容行为，但不会接收隐藏归因请求头。
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@ -733,7 +744,7 @@ export AZURE_OPENAI_API_VERSION="2024-12-01-preview"
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="模型选择" href="/zh-CN/concepts/model-providers" icon="layers">
|
||||
选择 provider、模型引用和故障转移行为。
|
||||
选择 provider、模型引用和故障切换行为。
|
||||
</Card>
|
||||
<Card title="图像生成" href="/zh-CN/tools/image-generation" icon="image">
|
||||
共享图像工具参数和 provider 选择。
|
||||
@ -741,7 +752,7 @@ export AZURE_OPENAI_API_VERSION="2024-12-01-preview"
|
||||
<Card title="视频生成" href="/zh-CN/tools/video-generation" icon="video">
|
||||
共享视频工具参数和 provider 选择。
|
||||
</Card>
|
||||
<Card title="OAuth 和认证" href="/zh-CN/gateway/authentication" icon="key">
|
||||
认证细节和凭证复用规则。
|
||||
<Card title="OAuth 与身份验证" href="/zh-CN/gateway/authentication" icon="key">
|
||||
身份验证详情和凭证复用规则。
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
@ -1,96 +1,91 @@
|
||||
---
|
||||
read_when:
|
||||
- 你想配置 memory 搜索提供商或 embedding 模型
|
||||
- 你想设置 QMD 后端】【。analysis to=functions.read commentary 天天中彩票中奖json 787 content omitted due to length?
|
||||
- 你想调优混合搜索、MMR 或时间衰减
|
||||
- 你想启用多模态 memory 索引
|
||||
summary: 有关 memory 搜索、embedding 提供商、QMD、混合搜索和多模态索引的全部配置项
|
||||
title: Memory 配置参考
|
||||
- 你想要配置内存搜索提供商或嵌入模型
|
||||
- 你想要设置 QMD 后端
|
||||
- 你想要调整混合搜索、MMR 或时间衰减
|
||||
- 你想要启用多模态内存索引
|
||||
summary: 内存搜索、嵌入提供商、QMD、混合搜索和多模态索引的所有配置项
|
||||
title: 内存配置参考
|
||||
x-i18n:
|
||||
generated_at: "2026-04-23T21:03:29Z"
|
||||
generated_at: "2026-04-23T21:49:30Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 2e179b955ee0532805ee254d79217b66c093def534c2ef3952d955b3b05de8ca
|
||||
source_hash: e8f91c15c149feb1a351585d246f3155ce56164cbda3e773dd63ebfa6c1b63b7
|
||||
source_path: reference/memory-config.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
本页列出了 OpenClaw memory 搜索的所有配置项。关于概念性概览，请参见：
|
||||
此页面列出了 OpenClaw 内存搜索的所有配置项。有关概念概览，请参阅：
|
||||
|
||||
- [Memory Overview](/zh-CN/concepts/memory) —— memory 的工作方式
|
||||
- [Builtin Engine](/zh-CN/concepts/memory-builtin) —— 默认 SQLite 后端
|
||||
- [QMD Engine](/zh-CN/concepts/memory-qmd) —— 本地优先 sidecar
|
||||
- [Memory Search](/zh-CN/concepts/memory-search) —— 搜索管线和调优
|
||||
- [Memory Overview](/zh-CN/concepts/memory) —— 内存的工作方式
|
||||
- [Builtin Engine](/zh-CN/concepts/memory-builtin) —— 默认的 SQLite 后端
|
||||
- [QMD Engine](/zh-CN/concepts/memory-qmd) —— 本地优先的 sidecar
|
||||
- [Memory Search](/zh-CN/concepts/memory-search) —— 搜索流水线与调优
|
||||
- [Active Memory](/zh-CN/concepts/active-memory) —— 为交互式会话启用 memory 子智能体
|
||||
|
||||
除特别说明外，所有 memory 搜索设置都位于
|
||||
`openclaw.json` 的 `agents.defaults.memorySearch` 下。
|
||||
除非另有说明，所有内存搜索设置都位于 `openclaw.json` 中的 `agents.defaults.memorySearch` 下。
|
||||
|
||||
如果你在找的是 **active memory** 功能开关和子智能体配置，
|
||||
它位于 `plugins.entries.active-memory` 下，而不是 `memorySearch`。
|
||||
如果你要查找 **active memory** 功能开关和子智能体配置，这些内容位于 `plugins.entries.active-memory` 下，而不是 `memorySearch`。
|
||||
|
||||
Active memory 使用双门控模型：
|
||||
|
||||
1. 插件必须已启用，并且目标指向当前智能体 id
|
||||
1. 必须启用该插件，并将其目标指向当前智能体 ID
|
||||
2. 请求必须是符合条件的交互式持久聊天会话
|
||||
|
||||
关于激活模型、插件自有配置、transcript 持久化和安全上线模式，
|
||||
请参见 [Active Memory](/zh-CN/concepts/active-memory)。
|
||||
有关激活模型、插件自有配置、转录持久化以及安全发布模式，请参阅 [Active Memory](/zh-CN/concepts/active-memory)。
|
||||
|
||||
---
|
||||
|
||||
## 提供商选择
|
||||
|
||||
| 键 | 类型 | 默认值 | 描述 |
|
||||
| Key | Type | Default | Description |
|
||||
| ---------- | --------- | ---------------- | ------------------------------------------------------------------------------------------------------------- |
|
||||
| `provider` | `string` | 自动检测 | Embedding 适配器 id：`bedrock`、`gemini`、`github-copilot`、`local`、`mistral`、`ollama`、`openai`、`voyage` |
|
||||
| `model` | `string` | 提供商默认值 | Embedding 模型名称 |
|
||||
| `fallback` | `string` | `"none"` | 主适配器失败时使用的回退适配器 id |
|
||||
| `enabled` | `boolean` | `true` | 启用或禁用 memory 搜索 |
|
||||
| `provider` | `string` | 自动检测 | 嵌入适配器 ID：`bedrock`、`gemini`、`github-copilot`、`local`、`mistral`、`ollama`、`openai`、`voyage` |
|
||||
| `model` | `string` | 提供商默认值 | 嵌入模型名称 |
|
||||
| `fallback` | `string` | `"none"` | 当主提供商失败时使用的回退适配器 ID |
|
||||
| `enabled` | `boolean` | `true` | 启用或禁用内存搜索 |
|
||||
|
||||
### 自动检测顺序
|
||||
|
||||
当未设置 `provider` 时，OpenClaw 会选择第一个可用项：
|
||||
|
||||
1. `local` —— 如果配置了 `memorySearch.local.modelPath` 且文件存在。
|
||||
2. `github-copilot` —— 如果 GitHub Copilot token 可解析（环境变量或 auth profile）。
|
||||
3. `openai` —— 如果 OpenAI key 可解析。
|
||||
4. `gemini` —— 如果 Gemini key 可解析。
|
||||
5. `voyage` —— 如果 Voyage key 可解析。
|
||||
6. `mistral` —— 如果 Mistral key 可解析。
|
||||
7. `bedrock` —— 如果 AWS SDK 凭证链可解析（实例角色、access key、profile、SSO、web identity 或共享配置）。
|
||||
1. `local` —— 如果已配置 `memorySearch.local.modelPath` 且文件存在。
|
||||
2. `github-copilot` —— 如果可以解析到 GitHub Copilot 令牌（环境变量或认证配置文件）。
|
||||
3. `openai` —— 如果可以解析到 OpenAI 密钥。
|
||||
4. `gemini` —— 如果可以解析到 Gemini 密钥。
|
||||
5. `voyage` —— 如果可以解析到 Voyage 密钥。
|
||||
6. `mistral` —— 如果可以解析到 Mistral 密钥。
|
||||
7. `bedrock` —— 如果 AWS SDK 凭证链可解析（实例角色、访问密钥、profile、SSO、web identity 或共享配置）。
|
||||
|
||||
支持 `ollama`，但不会自动检测（请显式设置）。
|
||||
|
||||
### API key 解析
|
||||
### API 密钥解析
|
||||
|
||||
远程 embeddings 需要 API key。Bedrock 则改用 AWS SDK 默认
|
||||
凭证链（实例角色、SSO、access key）。
|
||||
远程嵌入需要 API 密钥。Bedrock 则使用 AWS SDK 默认凭证链（实例角色、SSO、访问密钥）。
|
||||
|
||||
| 提供商 | 环境变量 | 配置键 |
|
||||
| Provider | Env var | Config key |
|
||||
| -------------- | -------------------------------------------------- | --------------------------------- |
|
||||
| Bedrock | AWS 凭证链 | 不需要 API key |
|
||||
| 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` |
|
||||
| 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` |
|
||||
|
||||
Codex OAuth 仅覆盖 chat/completions，不满足 embedding
|
||||
请求。
|
||||
Codex OAuth 仅适用于聊天/补全，不满足嵌入请求的要求。
|
||||
|
||||
---
|
||||
|
||||
## 远程端点配置
|
||||
|
||||
用于自定义 OpenAI 兼容端点，或覆盖提供商默认值：
|
||||
用于自定义 OpenAI 兼容端点或覆盖提供商默认值：
|
||||
|
||||
| 键 | 类型 | 描述 |
|
||||
| ---------------- | -------- | -------------------------------------------------- |
|
||||
| `remote.baseUrl` | `string` | 自定义 API base URL |
|
||||
| `remote.apiKey` | `string` | 覆盖 API key |
|
||||
| `remote.headers` | `object` | 额外 HTTP 请求头（与提供商默认值合并） |
|
||||
| Key | Type | Description |
|
||||
| ---------------- | -------- | --------------------------------------- |
|
||||
| `remote.baseUrl` | `string` | 自定义 API 基础 URL |
|
||||
| `remote.apiKey` | `string` | 覆盖 API 密钥 |
|
||||
| `remote.headers` | `object` | 额外的 HTTP 请求头（与提供商默认值合并） |
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -111,24 +106,23 @@ Codex OAuth 仅覆盖 chat/completions，不满足 embedding
|
||||
|
||||
---
|
||||
|
||||
## Gemini 专用配置
|
||||
## Gemini 专属配置
|
||||
|
||||
| 键 | 类型 | 默认值 | 描述 |
|
||||
| ---------------------- | -------- | ---------------------- | ------------------------------------------ |
|
||||
| `model` | `string` | `gemini-embedding-001` | 也支持 `gemini-embedding-2-preview` |
|
||||
| `outputDimensionality` | `number` | `3072` | 对于 Embedding 2：768、1536 或 3072 |
|
||||
| Key | Type | Default | Description |
|
||||
| ---------------------- | -------- | ---------------------- | ----------------------------------------- |
|
||||
| `model` | `string` | `gemini-embedding-001` | 也支持 `gemini-embedding-2-preview` |
|
||||
| `outputDimensionality` | `number` | `3072` | 对于 Embedding 2，可选 768、1536 或 3072 |
|
||||
|
||||
<Warning>
|
||||
更改模型或 `outputDimensionality` 会触发自动全量重建索引。
|
||||
更改模型或 `outputDimensionality` 会触发自动全量重新索引。
|
||||
</Warning>
|
||||
|
||||
---
|
||||
|
||||
## Bedrock embedding 配置
|
||||
## Bedrock 嵌入配置
|
||||
|
||||
Bedrock 使用 AWS SDK 默认凭证链 —— 无需 API key。
|
||||
如果 OpenClaw 运行在带有 Bedrock 权限实例角色的 EC2 上，只需设置
|
||||
provider 和 model：
|
||||
Bedrock 使用 AWS SDK 默认凭证链 —— 不需要 API 密钥。
|
||||
如果 OpenClaw 运行在启用了 Bedrock 实例角色的 EC2 上，只需设置 provider 和 model：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -143,47 +137,45 @@ provider 和 model：
|
||||
}
|
||||
```
|
||||
|
||||
| 键 | 类型 | 默认值 | 描述 |
|
||||
| ---------------------- | -------- | ------------------------------ | ------------------------------- |
|
||||
| `model` | `string` | `amazon.titan-embed-text-v2:0` | 任意 Bedrock embedding 模型 ID |
|
||||
| `outputDimensionality` | `number` | 模型默认值 | 对于 Titan V2：256、512 或 1024 |
|
||||
| Key | Type | Default | Description |
|
||||
| ---------------------- | -------- | ------------------------------ | ------------------------------ |
|
||||
| `model` | `string` | `amazon.titan-embed-text-v2:0` | 任意 Bedrock 嵌入模型 ID |
|
||||
| `outputDimensionality` | `number` | 模型默认值 | 对于 Titan V2，可选 256、512 或 1024 |
|
||||
|
||||
### 支持的模型
|
||||
|
||||
支持以下模型（带有家族检测和默认维度）：
|
||||
以下模型受支持（包含系列检测和默认维度）：
|
||||
|
||||
| 模型 ID | 提供商 | 默认维度 | 可配置维度 |
|
||||
| Model ID | Provider | Default Dims | Configurable Dims |
|
||||
| ------------------------------------------ | ---------- | ------------ | -------------------- |
|
||||
| `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-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`）会继承
|
||||
基础模型的配置。
|
||||
带吞吐量后缀的变体（例如 `amazon.titan-embed-text-v1:2:8k`）会继承基础模型的配置。
|
||||
|
||||
### 认证
|
||||
|
||||
Bedrock 认证使用标准 AWS SDK 凭证解析顺序：
|
||||
|
||||
1. 环境变量（`AWS_ACCESS_KEY_ID` + `AWS_SECRET_ACCESS_KEY`）
|
||||
2. SSO token 缓存
|
||||
3. Web identity token 凭证
|
||||
2. SSO 令牌缓存
|
||||
3. Web identity 令牌凭证
|
||||
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 角色或用户需要具备：
|
||||
|
||||
```json
|
||||
{
|
||||
@ -193,7 +185,7 @@ IAM 角色或用户需要：
|
||||
}
|
||||
```
|
||||
|
||||
若要最小权限，请将 `InvokeModel` 限定到具体模型：
|
||||
为了实现最小权限，应将 `InvokeModel` 限定到特定模型：
|
||||
|
||||
```
|
||||
arn:aws:bedrock:*::foundation-model/amazon.titan-embed-text-v2:0
|
||||
@ -201,15 +193,16 @@ arn:aws:bedrock:*::foundation-model/amazon.titan-embed-text-v2:0
|
||||
|
||||
---
|
||||
|
||||
## 本地 embedding 配置
|
||||
## 本地嵌入配置
|
||||
|
||||
| 键 | 类型 | 默认值 | 描述 |
|
||||
| --------------------- | -------- | ---------------------- | ------------------------------- |
|
||||
| `local.modelPath` | `string` | 自动下载 | GGUF 模型文件路径 |
|
||||
| `local.modelCacheDir` | `string` | node-llama-cpp 默认值 | 下载模型的缓存目录 |
|
||||
| Key | Type | Default | Description |
|
||||
| --------------------- | ------------------ | ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `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`。
|
||||
需要原生构建：`pnpm approve-builds`，然后执行 `pnpm rebuild node-llama-cpp`。
|
||||
|
||||
---
|
||||
|
||||
@ -217,28 +210,28 @@ arn:aws:bedrock:*::foundation-model/amazon.titan-embed-text-v2:0
|
||||
|
||||
全部位于 `memorySearch.query.hybrid` 下：
|
||||
|
||||
| 键 | 类型 | 默认值 | 描述 |
|
||||
| --------------------- | --------- | ------- | ---------------------------------- |
|
||||
| `enabled` | `boolean` | `true` | 启用混合 BM25 + 向量搜索 |
|
||||
| `vectorWeight` | `number` | `0.7` | 向量分数权重（0-1） |
|
||||
| `textWeight` | `number` | `0.3` | BM25 分数权重（0-1） |
|
||||
| `candidateMultiplier` | `number` | `4` | 候选池大小乘数 |
|
||||
| Key | Type | Default | Description |
|
||||
| --------------------- | --------- | ------- | ------------------------------ |
|
||||
| `enabled` | `boolean` | `true` | 启用混合 BM25 + 向量搜索 |
|
||||
| `vectorWeight` | `number` | `0.7` | 向量分数权重（0-1） |
|
||||
| `textWeight` | `number` | `0.3` | BM25 分数权重（0-1） |
|
||||
| `candidateMultiplier` | `number` | `4` | 候选池大小乘数 |
|
||||
|
||||
### MMR（多样性）
|
||||
|
||||
| 键 | 类型 | 默认值 | 描述 |
|
||||
| ------------- | --------- | ------- | ------------------------------------ |
|
||||
| `mmr.enabled` | `boolean` | `false` | 启用 MMR 重排序 |
|
||||
| `mmr.lambda` | `number` | `0.7` | 0 = 最大多样性，1 = 最大相关性 |
|
||||
| Key | Type | Default | Description |
|
||||
| ------------- | --------- | ------- | ---------------------------------- |
|
||||
| `mmr.enabled` | `boolean` | `false` | 启用 MMR 重新排序 |
|
||||
| `mmr.lambda` | `number` | `0.7` | 0 = 最大多样性，1 = 最大相关性 |
|
||||
|
||||
### 时间衰减（新近性）
|
||||
|
||||
| 键 | 类型 | 默认值 | 描述 |
|
||||
| ---------------------------- | --------- | ------- | ------------------------- |
|
||||
| `temporalDecay.enabled` | `boolean` | `false` | 启用新近性加权 |
|
||||
| `temporalDecay.halfLifeDays` | `number` | `30` | 每 N 天分数减半 |
|
||||
| Key | Type | Default | Description |
|
||||
| ---------------------------- | --------- | ------- | -------------------- |
|
||||
| `temporalDecay.enabled` | `boolean` | `false` | 启用新近性加权 |
|
||||
| `temporalDecay.halfLifeDays` | `number` | `30` | 每 N 天分数减半 |
|
||||
|
||||
常青文件（`MEMORY.md`、`memory/` 中非日期命名文件）永远不会衰减。
|
||||
常青文件（`MEMORY.md`、`memory/` 中无日期的文件）永远不会衰减。
|
||||
|
||||
### 完整示例
|
||||
|
||||
@ -263,11 +256,11 @@ arn:aws:bedrock:*::foundation-model/amazon.titan-embed-text-v2:0
|
||||
|
||||
---
|
||||
|
||||
## 额外 memory 路径
|
||||
## 其他内存路径
|
||||
|
||||
| 键 | 类型 | 描述 |
|
||||
| ------------ | ---------- | ---------------------------------------- |
|
||||
| `extraPaths` | `string[]` | 额外需要索引的目录或文件 |
|
||||
| Key | Type | Description |
|
||||
| ------------ | ---------- | ------------------------------ |
|
||||
| `extraPaths` | `string[]` | 要建立索引的其他目录或文件 |
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -281,152 +274,137 @@ arn:aws:bedrock:*::foundation-model/amazon.titan-embed-text-v2:0
|
||||
}
|
||||
```
|
||||
|
||||
路径可以是绝对路径，也可以相对于工作区。目录会递归扫描
|
||||
`.md` 文件。符号链接处理取决于当前后端：
|
||||
内置引擎会忽略符号链接，而 QMD 会遵循底层 QMD
|
||||
扫描器行为。
|
||||
路径可以是绝对路径，也可以是相对于工作区的路径。目录会递归扫描 `.md` 文件。符号链接的处理取决于当前启用的后端：内置引擎会忽略符号链接，而 QMD 则遵循底层 QMD 扫描器的行为。
|
||||
|
||||
对于按智能体作用域的跨智能体 transcript 搜索，请使用
|
||||
`agents.list[].memorySearch.qmd.extraCollections`，而不是 `memory.qmd.paths`。
|
||||
这些额外 collection 使用相同的 `{ 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）
|
||||
|
||||
使用 Gemini Embedding 2 为图像和音频与 Markdown 一起建立索引：
|
||||
使用 Gemini Embedding 2 将图像和音频与 Markdown 一起建立索引：
|
||||
|
||||
| 键 | 类型 | 默认值 | 描述 |
|
||||
| ------------------------- | ---------- | ---------- | -------------------------------------- |
|
||||
| `multimodal.enabled` | `boolean` | `false` | 启用多模态索引 |
|
||||
| `multimodal.modalities` | `string[]` | -- | `["image"]`、`["audio"]` 或 `["all"]` |
|
||||
| `multimodal.maxFileBytes` | `number` | `10000000` | 用于索引的最大文件大小 |
|
||||
| Key | Type | Default | Description |
|
||||
| ------------------------- | ---------- | ---------- | ----------------------------------- |
|
||||
| `multimodal.enabled` | `boolean` | `false` | 启用多模态索引 |
|
||||
| `multimodal.modalities` | `string[]` | -- | `["image"]`、`["audio"]` 或 `["all"]` |
|
||||
| `multimodal.maxFileBytes` | `number` | `10000000` | 建立索引时允许的最大文件大小 |
|
||||
|
||||
仅适用于 `extraPaths` 中的文件。默认 memory 根目录仍然只处理 Markdown。
|
||||
要求使用 `gemini-embedding-2-preview`。`fallback` 必须为 `"none"`。
|
||||
仅适用于 `extraPaths` 中的文件。默认内存根目录仍然只支持 Markdown。
|
||||
需要 `gemini-embedding-2-preview`。`fallback` 必须为 `"none"`。
|
||||
|
||||
支持的格式：`.jpg`、`.jpeg`、`.png`、`.webp`、`.gif`、`.heic`、`.heif`
|
||||
（图像）；`.mp3`、`.wav`、`.ogg`、`.opus`、`.m4a`、`.aac`、`.flac`（音频）。
|
||||
|
||||
---
|
||||
|
||||
## Embedding 缓存
|
||||
## 嵌入缓存
|
||||
|
||||
| 键 | 类型 | 默认值 | 描述 |
|
||||
| ------------------ | --------- | ------- | -------------------------------- |
|
||||
| `cache.enabled` | `boolean` | `false` | 在 SQLite 中缓存 chunk embedding |
|
||||
| `cache.maxEntries` | `number` | `50000` | 最大缓存 embedding 数 |
|
||||
| Key | Type | Default | Description |
|
||||
| ------------------ | --------- | ------- | ------------------------------- |
|
||||
| `cache.enabled` | `boolean` | `false` | 在 SQLite 中缓存分块嵌入 |
|
||||
| `cache.maxEntries` | `number` | `50000` | 最大缓存嵌入数量 |
|
||||
|
||||
可防止在重建索引或 transcript 更新时，对未更改的文本重复进行 embedding。
|
||||
可防止在重新索引或更新转录时，对未更改的文本重复生成嵌入。
|
||||
|
||||
---
|
||||
|
||||
## 批量索引
|
||||
|
||||
| 键 | 类型 | 默认值 | 描述 |
|
||||
| ----------------------------- | --------- | ------- | -------------------------- |
|
||||
| `remote.batch.enabled` | `boolean` | `false` | 启用批量 embedding API |
|
||||
| `remote.batch.concurrency` | `number` | `2` | 并行批处理作业数 |
|
||||
| `remote.batch.wait` | `boolean` | `true` | 等待批处理完成 |
|
||||
| `remote.batch.pollIntervalMs` | `number` | -- | 轮询间隔 |
|
||||
| `remote.batch.timeoutMinutes` | `number` | -- | 批处理超时 |
|
||||
| Key | Type | Default | Description |
|
||||
| ----------------------------- | --------- | ------- | ------------------------ |
|
||||
| `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 批处理通常最快且成本最低。
|
||||
|
||||
---
|
||||
|
||||
## 会话 memory 搜索（实验性）
|
||||
## 会话内存搜索（实验性）
|
||||
|
||||
为会话 transcript 建立索引，并通过 `memory_search` 暴露出来：
|
||||
为会话转录建立索引，并通过 `memory_search` 暴露：
|
||||
|
||||
| 键 | 类型 | 默认值 | 描述 |
|
||||
| Key | Type | Default | Description |
|
||||
| ----------------------------- | ---------- | ------------ | --------------------------------------- |
|
||||
| `experimental.sessionMemory` | `boolean` | `false` | 启用会话索引 |
|
||||
| `sources` | `string[]` | `["memory"]` | 添加 `"sessions"` 以包含 transcript |
|
||||
| `sync.sessions.deltaBytes` | `number` | `100000` | 触发重建索引的字节阈值 |
|
||||
| `sync.sessions.deltaMessages` | `number` | `50` | 触发重建索引的消息阈值 |
|
||||
| `experimental.sessionMemory` | `boolean` | `false` | 启用会话索引 |
|
||||
| `sources` | `string[]` | `["memory"]` | 添加 `"sessions"` 以包含转录 |
|
||||
| `sync.sessions.deltaBytes` | `number` | `100000` | 触发重新索引的字节阈值 |
|
||||
| `sync.sessions.deltaMessages` | `number` | `50` | 触发重新索引的消息阈值 |
|
||||
|
||||
会话索引是选择启用功能，并且异步运行。结果可能会有轻微
|
||||
滞后。会话日志存储在磁盘上，因此请将文件系统访问视为信任
|
||||
边界。
|
||||
会话索引需要显式启用，并以异步方式运行。结果可能会有轻微滞后。会话日志保存在磁盘上，因此应将文件系统访问视为信任边界。
|
||||
|
||||
---
|
||||
|
||||
## SQLite 向量加速（sqlite-vec）
|
||||
|
||||
| 键 | 类型 | 默认值 | 描述 |
|
||||
| ---------------------------- | --------- | ------- | --------------------------------- |
|
||||
| `store.vector.enabled` | `boolean` | `true` | 使用 sqlite-vec 执行向量查询 |
|
||||
| `store.vector.extensionPath` | `string` | bundled | 覆盖 sqlite-vec 路径 |
|
||||
| Key | Type | Default | Description |
|
||||
| ---------------------------- | --------- | ------- | ---------------------------------- |
|
||||
| `store.vector.enabled` | `boolean` | `true` | 使用 sqlite-vec 执行向量查询 |
|
||||
| `store.vector.extensionPath` | `string` | bundled | 覆盖 sqlite-vec 路径 |
|
||||
|
||||
当 sqlite-vec 不可用时，OpenClaw 会自动回退到进程内 cosine
|
||||
similarity。
|
||||
当 sqlite-vec 不可用时，OpenClaw 会自动回退到进程内余弦相似度计算。
|
||||
|
||||
---
|
||||
|
||||
## 索引存储
|
||||
|
||||
| 键 | 类型 | 默认值 | 描述 |
|
||||
| --------------------- | -------- | ------------------------------------- | ------------------------------------------- |
|
||||
| `store.path` | `string` | `~/.openclaw/memory/{agentId}.sqlite` | 索引位置（支持 `{agentId}` token） |
|
||||
| `store.fts.tokenizer` | `string` | `unicode61` | FTS5 tokenizer（`unicode61` 或 `trigram`） |
|
||||
| Key | Type | Default | Description |
|
||||
| --------------------- | -------- | ------------------------------------- | --------------------------------------- |
|
||||
| `store.path` | `string` | `~/.openclaw/memory/{agentId}.sqlite` | 索引位置（支持 `{agentId}` 占位符） |
|
||||
| `store.fts.tokenizer` | `string` | `unicode61` | FTS5 分词器（`unicode61` 或 `trigram`） |
|
||||
|
||||
---
|
||||
|
||||
## QMD 后端配置
|
||||
|
||||
设置 `memory.backend = "qmd"` 以启用。所有 QMD 设置位于
|
||||
设置 `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` | 为会话 transcript 建立索引 |
|
||||
| `sessions.retentionDays` | `number` | -- | Transcript 保留期 |
|
||||
| `sessions.exportDir` | `string` | -- | 导出目录 |
|
||||
| Key | Type | Default | Description |
|
||||
| ------------------------ | --------- | -------- | ------------------------------------------ |
|
||||
| `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.exportDir` | `string` | -- | 导出目录 |
|
||||
|
||||
OpenClaw 会优先使用当前的 QMD collection 和 MCP 查询形态，但仍通过回退到旧版 `--mask` collection 标志
|
||||
和旧版 MCP 工具名来兼容较老版本的 QMD。
|
||||
OpenClaw 优先使用当前 QMD collection 和 MCP 查询结构，但也会通过回退到旧版 `--mask` collection 标志和旧版 MCP 工具名称，在需要时继续兼容较旧的 QMD 版本。
|
||||
|
||||
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`。
|
||||
|
||||
### 更新计划
|
||||
|
||||
| 键 | 类型 | 默认值 | 描述 |
|
||||
| ------------------------- | --------- | ------- | ------------------------------------- |
|
||||
| `update.interval` | `string` | `5m` | 刷新间隔 |
|
||||
| `update.debounceMs` | `number` | `15000` | 文件更改防抖时间 |
|
||||
| `update.onBoot` | `boolean` | `true` | 启动时刷新 |
|
||||
| `update.waitForBootSync` | `boolean` | `false` | 在刷新完成前阻塞启动 |
|
||||
| `update.embedInterval` | `string` | -- | 单独的 embed 频率 |
|
||||
| `update.commandTimeoutMs` | `number` | -- | QMD 命令超时 |
|
||||
| `update.updateTimeoutMs` | `number` | -- | QMD update 操作超时 |
|
||||
| `update.embedTimeoutMs` | `number` | -- | QMD embed 操作超时 |
|
||||
| Key | Type | Default | Description |
|
||||
| ------------------------- | --------- | ------- | -------------------------------- |
|
||||
| `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 嵌入操作超时时间 |
|
||||
|
||||
### 限制
|
||||
|
||||
| 键 | 类型 | 默认值 | 描述 |
|
||||
| ------------------------- | -------- | ------- | -------------------------- |
|
||||
| `limits.maxResults` | `number` | `6` | 最大搜索结果数 |
|
||||
| `limits.maxSnippetChars` | `number` | -- | 限制片段长度 |
|
||||
| `limits.maxInjectedChars` | `number` | -- | 限制注入总字符数 |
|
||||
| `limits.timeoutMs` | `number` | `4000` | 搜索超时 |
|
||||
| Key | Type | Default | Description |
|
||||
| ------------------------- | -------- | ------- | ---------------------- |
|
||||
| `limits.maxResults` | `number` | `6` | 最大搜索结果数 |
|
||||
| `limits.maxSnippetChars` | `number` | -- | 限制摘要长度 |
|
||||
| `limits.maxInjectedChars` | `number` | -- | 限制注入的总字符数 |
|
||||
| `limits.timeoutMs` | `number` | `4000` | 搜索超时时间 |
|
||||
|
||||
### 范围
|
||||
### 作用域
|
||||
|
||||
控制哪些会话可以接收 QMD 搜索结果。其 schema 与
|
||||
[`session.sendPolicy`](/zh-CN/gateway/configuration-reference#session) 相同：
|
||||
用于控制哪些会话可以接收 QMD 搜索结果。使用与
|
||||
[`session.sendPolicy`](/zh-CN/gateway/configuration-reference#session) 相同的 schema：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -441,21 +419,20 @@ QMD 模型覆盖保留在 QMD 侧，而不是 OpenClaw 配置中。如果你需
|
||||
}
|
||||
```
|
||||
|
||||
内置默认值允许 direct 和 channel 会话，同时仍拒绝
|
||||
group。
|
||||
随附的默认配置允许 direct 和 channel 会话，同时仍然拒绝 group。
|
||||
|
||||
默认值为仅私信。`match.keyPrefix` 匹配规范化后的会话键；
|
||||
`match.rawKeyPrefix` 匹配包含 `agent:<id>:` 的原始键。
|
||||
默认仅限私信。`match.keyPrefix` 匹配规范化后的会话键；
|
||||
`match.rawKeyPrefix` 匹配原始键，包括 `agent:<id>:`。
|
||||
|
||||
### 引用
|
||||
|
||||
`memory.citations` 适用于所有后端：
|
||||
|
||||
| 值 | 行为 |
|
||||
| ---------------- | --------------------------------------------------- |
|
||||
| `auto`（默认） | 在片段中包含 `Source: <path#line>` 页脚 |
|
||||
| `on` | 始终包含页脚 |
|
||||
| `off` | 省略页脚（路径仍会在内部传给智能体） |
|
||||
| Value | Behavior |
|
||||
| ---------------- | ----------------------------------------- |
|
||||
| `auto`（默认） | 在摘要中包含 `Source: <path#line>` 页脚 |
|
||||
| `on` | 始终包含页脚 |
|
||||
| `off` | 省略页脚（路径仍会在内部传递给智能体） |
|
||||
|
||||
### 完整 QMD 示例
|
||||
|
||||
@ -483,19 +460,18 @@ group。
|
||||
## Dreaming
|
||||
|
||||
Dreaming 配置位于 `plugins.entries.memory-core.config.dreaming` 下，
|
||||
而不是 `agents.defaults.memorySearch`。
|
||||
而不是 `agents.defaults.memorySearch` 下。
|
||||
|
||||
Dreaming 作为一次计划好的完整 sweep 运行，并将内部 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 sweep 的可选 cron 频率 |
|
||||
| Key | Type | Default | Description |
|
||||
| ----------- | --------- | ----------- | ----------------------------------- |
|
||||
| `enabled` | `boolean` | `false` | 完全启用或禁用 Dreaming |
|
||||
| `frequency` | `string` | `0 3 * * *` | 可选的完整 Dreaming 扫描 cron 周期 |
|
||||
|
||||
### 示例
|
||||
|
||||
@ -519,5 +495,5 @@ Dreaming 作为一次计划好的完整 sweep 运行，并将内部 light/deep/R
|
||||
说明：
|
||||
|
||||
- Dreaming 会将机器状态写入 `memory/.dreams/`。
|
||||
- Dreaming 会将人类可读的叙事输出写入 `DREAMS.md`（或已有的 `dreams.md`）。
|
||||
- Dreaming 会将人类可读的叙事输出写入 `DREAMS.md`（或现有的 `dreams.md`）。
|
||||
- light/deep/REM 阶段策略和阈值属于内部行为，不是面向用户的配置。
|
||||
|
||||
@ -1,29 +1,29 @@
|
||||
---
|
||||
read_when:
|
||||
- 通过智能体生成图像
|
||||
- 配置图像生成 providers 和模型
|
||||
- 理解 `image_generate` 工具参数
|
||||
summary: 使用已配置的 providers（OpenAI、Google Gemini、fal、MiniMax、ComfyUI、Vydra、xAI）生成和编辑图像
|
||||
- 配置图像生成提供商和模型
|
||||
- 了解 `image_generate` 工具参数
|
||||
summary: 使用已配置的提供商（OpenAI、OpenAI Codex OAuth、Google Gemini、fal、MiniMax、ComfyUI、Vydra、xAI）生成和编辑图像
|
||||
title: 图像生成
|
||||
x-i18n:
|
||||
generated_at: "2026-04-23T21:08:28Z"
|
||||
generated_at: "2026-04-23T21:49:31Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 2ca23553fa80fbc286046baa2bdb639aab76a24f2d55dc1764085f57b24be29e
|
||||
source_hash: efba2038e097843053a33f2afe3e98d22a83d79fefc84872c2c7c47dbe888dc0
|
||||
source_path: tools/image-generation.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
`image_generate` 工具让智能体能够使用你已配置的 providers 创建和编辑图像。生成的图像会自动作为媒体附件附加在智能体回复中发送。
|
||||
`image_generate` 工具允许智能体使用你已配置的提供商创建和编辑图像。生成的图像会作为媒体附件自动包含在智能体的回复中。
|
||||
|
||||
<Note>
|
||||
只有当至少有一个图像生成 provider 可用时，该工具才会出现。如果你没有在智能体工具中看到 `image_generate`，请配置 `agents.defaults.imageGenerationModel` 或设置 provider API 密钥。
|
||||
只有在至少有一个图像生成提供商可用时，此工具才会显示。如果你在智能体的工具中看不到 `image_generate`，请配置 `agents.defaults.imageGenerationModel`、设置提供商 API 密钥，或使用 OpenAI Codex OAuth 登录。
|
||||
</Note>
|
||||
|
||||
## 快速开始
|
||||
|
||||
1. 至少为一个 provider 设置 API 密钥（例如 `OPENAI_API_KEY` 或 `GEMINI_API_KEY`）。
|
||||
2. 可选地设置你偏好的模型：
|
||||
1. 为至少一个提供商设置 API 密钥（例如 `OPENAI_API_KEY` 或 `GEMINI_API_KEY`），或使用 OpenAI Codex OAuth 登录。
|
||||
2. 可选：设置你偏好的模型：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -37,47 +37,48 @@ x-i18n:
|
||||
}
|
||||
```
|
||||
|
||||
3. 对智能体说：_“生成一张友好龙虾吉祥物的图像。”_
|
||||
Codex OAuth 使用相同的 `openai/gpt-image-2` 模型引用。如果没有可用的 `OPENAI_API_KEY`，OpenClaw 会解析现有的 `openai-codex` OAuth 配置文件，并通过 Codex Responses 后端发送图像请求。
|
||||
|
||||
智能体会自动调用 `image_generate`。无需手动加入工具允许列表——只要 provider 可用，它默认就是启用的。
|
||||
3. 向智能体发出请求：_“生成一张友好机器人吉祥物的图像。”_
|
||||
|
||||
## 支持的 providers
|
||||
智能体会自动调用 `image_generate`。无需工具允许列表——当提供商可用时，它默认启用。
|
||||
|
||||
| Provider | 默认模型 | 编辑支持 | API 密钥 |
|
||||
| ------------ | -------------------------------- | --------------------------------- | ------------------------------------------------------ |
|
||||
| OpenAI | `gpt-image-2` | 是（最多 4 张图像） | `OPENAI_API_KEY` |
|
||||
| OpenAI Codex | `gpt-image-2` | 是（最多 4 张图像） | OpenAI Codex OAuth |
|
||||
| Google | `gemini-3.1-flash-image-preview` | 是 | `GEMINI_API_KEY` 或 `GOOGLE_API_KEY` |
|
||||
| fal | `fal-ai/flux/dev` | 是 | `FAL_KEY` |
|
||||
| MiniMax | `image-01` | 是（主体参考） | `MINIMAX_API_KEY` 或 MiniMax OAuth（`minimax-portal`） |
|
||||
| ComfyUI | `workflow` | 是（1 张图像，由工作流配置） | 云端需要 `COMFY_API_KEY` 或 `COMFY_CLOUD_API_KEY` |
|
||||
| Vydra | `grok-imagine` | 否 | `VYDRA_API_KEY` |
|
||||
| xAI | `grok-imagine-image` | 是（最多 5 张图像） | `XAI_API_KEY` |
|
||||
## 支持的提供商
|
||||
|
||||
使用 `action: "list"` 可以在运行时检查可用 providers 和模型：
|
||||
| 提供商 | 默认模型 | 编辑支持 | 认证 |
|
||||
| -------- | -------------------------------- | ---------------------------------- | ----------------------------------------------------- |
|
||||
| OpenAI | `gpt-image-2` | 是（最多 4 张图像） | `OPENAI_API_KEY` 或 OpenAI Codex OAuth |
|
||||
| Google | `gemini-3.1-flash-image-preview` | 是 | `GEMINI_API_KEY` 或 `GOOGLE_API_KEY` |
|
||||
| fal | `fal-ai/flux/dev` | 是 | `FAL_KEY` |
|
||||
| MiniMax | `image-01` | 是（主体参考） | `MINIMAX_API_KEY` 或 MiniMax OAuth (`minimax-portal`) |
|
||||
| ComfyUI | `workflow` | 是（1 张图像，由工作流配置） | 云端使用 `COMFY_API_KEY` 或 `COMFY_CLOUD_API_KEY` |
|
||||
| Vydra | `grok-imagine` | 否 | `VYDRA_API_KEY` |
|
||||
| xAI | `grok-imagine-image` | 是（最多 5 张图像） | `XAI_API_KEY` |
|
||||
|
||||
```text
|
||||
使用 `action: "list"` 可在运行时检查可用的提供商和模型：
|
||||
|
||||
```
|
||||
/tool image_generate action=list
|
||||
```
|
||||
|
||||
## 工具参数
|
||||
|
||||
| 参数 | 类型 | 说明 |
|
||||
| ------------- | --------- | ---------------------------------------------------------------------------------------- |
|
||||
| `prompt` | string | 图像生成提示（`action: "generate"` 时必填） |
|
||||
| `action` | string | `"generate"`（默认）或 `"list"`，用于查看 providers |
|
||||
| `model` | string | Provider/模型覆盖，例如 `openai/gpt-image-2` |
|
||||
| `image` | string | 编辑模式下的单张参考图像路径或 URL |
|
||||
| `images` | string[] | 编辑模式下的多张参考图像（最多 5 张） |
|
||||
| `size` | string | 尺寸提示：`1024x1024`、`1536x1024`、`1024x1536`、`2048x2048`、`3840x2160` |
|
||||
| `aspectRatio` | string | 宽高比：`1:1`、`2:3`、`3:2`、`3:4`、`4:3`、`4:5`、`5:4`、`9:16`、`16:9`、`21:9` |
|
||||
| `resolution` | string | 分辨率提示：`1K`、`2K` 或 `4K` |
|
||||
| `count` | number | 要生成的图像数量（1–4） |
|
||||
| `filename` | string | 输出文件名提示 |
|
||||
| 参数 | 类型 | 说明 |
|
||||
| ------------- | -------- | ------------------------------------------------------------------------------------- |
|
||||
| `prompt` | string | 图像生成提示词（`action: "generate"` 时必需） |
|
||||
| `action` | string | `"generate"`（默认）或 `"list"`，用于查看提供商 |
|
||||
| `model` | string | 提供商/模型覆盖，例如 `openai/gpt-image-2` |
|
||||
| `image` | string | 编辑模式下的单张参考图像路径或 URL |
|
||||
| `images` | string[] | 编辑模式下的多张参考图像（最多 5 张） |
|
||||
| `size` | string | 尺寸提示：`1024x1024`、`1536x1024`、`1024x1536`、`2048x2048`、`3840x2160` |
|
||||
| `aspectRatio` | string | 宽高比：`1:1`、`2:3`、`3:2`、`3:4`、`4:3`、`4:5`、`5:4`、`9:16`、`16:9`、`21:9` |
|
||||
| `resolution` | string | 分辨率提示：`1K`、`2K` 或 `4K` |
|
||||
| `count` | number | 要生成的图像数量（1–4） |
|
||||
| `filename` | string | 输出文件名提示 |
|
||||
|
||||
并非所有 providers 都支持所有参数。当某个回退 provider 支持的是接近的几何选项而不是精确请求值时，OpenClaw 会在提交前将其重新映射为最接近的受支持 size、aspect ratio 或 resolution。真正不受支持的覆盖项仍会在工具结果中报告。
|
||||
并非所有提供商都支持所有参数。当某个回退提供商支持接近的几何选项而非你精确请求的选项时，OpenClaw 会在提交前重新映射为最接近的受支持尺寸、宽高比或分辨率。真正不支持的覆盖项仍会在工具结果中报告。
|
||||
|
||||
工具结果会报告实际应用的设置。当 OpenClaw 在 provider 回退期间重新映射几何参数时，返回的 `size`、`aspectRatio` 和 `resolution` 值会反映实际发送的内容，而 `details.normalization` 则会记录从请求值到应用值的转换过程。
|
||||
工具结果会报告实际应用的设置。当 OpenClaw 在提供商回退期间重新映射几何参数时，返回的 `size`、`aspectRatio` 和 `resolution` 值会反映实际发送的内容，而 `details.normalization` 会记录从请求值到应用值的转换。
|
||||
|
||||
## 配置
|
||||
|
||||
@ -96,117 +97,104 @@ x-i18n:
|
||||
}
|
||||
```
|
||||
|
||||
### Provider 选择顺序
|
||||
### 提供商选择顺序
|
||||
|
||||
生成图像时，OpenClaw 会按以下顺序尝试 providers：
|
||||
生成图像时，OpenClaw 会按以下顺序尝试提供商：
|
||||
|
||||
1. 工具调用中的 **`model` 参数**（如果智能体显式指定）
|
||||
1. 工具调用中的 **`model` 参数**（如果智能体指定了该参数）
|
||||
2. 配置中的 **`imageGenerationModel.primary`**
|
||||
3. 按顺序尝试 **`imageGenerationModel.fallbacks`**
|
||||
4. **自动检测** —— 仅使用基于认证的 provider 默认值：
|
||||
- 当前默认 provider 优先
|
||||
- 其余已注册图像生成 providers，按 provider-id 顺序排列
|
||||
3. 按顺序使用 **`imageGenerationModel.fallbacks`**
|
||||
4. **自动检测** —— 仅使用具备认证支持的提供商默认值：
|
||||
- 当前默认提供商优先
|
||||
- 其余已注册图像生成提供商，按 provider-id 顺序
|
||||
|
||||
如果某个 provider 失败（认证错误、限流等），系统会自动尝试下一个候选项。如果全部失败，错误中会包含每次尝试的详细信息。
|
||||
如果某个提供商失败（认证错误、速率限制等），会自动尝试下一个候选项。如果全部失败，错误信息会包含每次尝试的详细信息。
|
||||
|
||||
说明：
|
||||
注意：
|
||||
|
||||
- 自动检测是带认证感知的。只有当 OpenClaw 实际能够认证该 provider 时，该 provider 默认值
|
||||
才会进入候选列表。
|
||||
- 自动检测默认启用。若你希望图像
|
||||
生成仅使用显式 `model`、`primary` 和 `fallbacks`
|
||||
条目，请设置
|
||||
`agents.defaults.mediaGenerationAutoProviderFallback: false`。
|
||||
- 使用 `action: "list"` 可以查看当前已注册的 providers、它们的默认模型，以及认证环境变量提示。
|
||||
- 自动检测具备认证感知能力。只有当 OpenClaw 实际能够对某个提供商进行认证时，该提供商默认值才会进入候选列表。
|
||||
- 自动检测默认启用。如果你希望图像生成仅使用显式的 `model`、`primary` 和 `fallbacks` 条目，请设置 `agents.defaults.mediaGenerationAutoProviderFallback: false`。
|
||||
- 使用 `action: "list"` 可检查当前已注册的提供商、它们的默认模型以及认证环境变量提示。
|
||||
|
||||
### 图像编辑
|
||||
|
||||
OpenAI、Google、fal、MiniMax、ComfyUI 和 xAI 支持编辑参考图像。传入参考图像路径或 URL：
|
||||
|
||||
```text
|
||||
"Generate a watercolor version of this photo" + image: "/path/to/photo.jpg"
|
||||
```
|
||||
"生成这张照片的水彩版本" + image: "/path/to/photo.jpg"
|
||||
```
|
||||
|
||||
OpenAI、Google 和 xAI 通过 `images` 参数支持最多 5 张参考图像。fal、MiniMax 和 ComfyUI 支持 1 张。
|
||||
OpenAI、Google 和 xAI 通过 `images` 参数最多支持 5 张参考图像。fal、MiniMax 和 ComfyUI 支持 1 张。
|
||||
|
||||
### OpenAI `gpt-image-2`
|
||||
|
||||
OpenAI 图像生成默认使用 `openai/gpt-image-2`。较旧的
|
||||
`openai/gpt-image-1` 模型仍然可以显式选择，但新的 OpenAI
|
||||
图像生成和图像编辑请求应使用 `gpt-image-2`。
|
||||
OpenAI 图像生成默认使用 `openai/gpt-image-2`。可用时会使用 `OPENAI_API_KEY`。如果未配置 API 密钥，OpenClaw 会复用与 Codex 订阅聊天模型相同的 `openai-codex` OAuth 配置文件，并通过 Codex Responses 后端发送图像请求。较旧的 `openai/gpt-image-1` 模型仍可显式选择，但新的 OpenAI 图像生成和图像编辑请求应使用 `gpt-image-2`。
|
||||
|
||||
`gpt-image-2` 通过同一个 `image_generate` 工具同时支持文生图生成和参考图像
|
||||
编辑。OpenClaw 会将 `prompt`、
|
||||
`count`、`size` 和参考图像转发给 OpenAI。OpenAI 不会直接接收
|
||||
`aspectRatio` 或 `resolution`；在可能的情况下，OpenClaw 会将它们映射为受支持的
|
||||
`size`，否则工具会将其报告为被忽略的覆盖项。
|
||||
`gpt-image-2` 同时支持文生图生成和通过同一个 `image_generate` 工具进行参考图像编辑。OpenClaw 会将 `prompt`、`count`、`size` 和参考图像转发给 OpenAI。OpenAI 不会直接接收 `aspectRatio` 或 `resolution`；在可能的情况下，OpenClaw 会将它们映射为受支持的 `size`，否则工具会将它们报告为被忽略的覆盖项。
|
||||
|
||||
生成一张 4K 横向图像：
|
||||
|
||||
```text
|
||||
```
|
||||
/tool image_generate action=generate model=openai/gpt-image-2 prompt="A clean editorial poster for OpenClaw image generation" size=3840x2160 count=1
|
||||
```
|
||||
|
||||
生成两张方形图像：
|
||||
|
||||
```text
|
||||
```
|
||||
/tool image_generate action=generate model=openai/gpt-image-2 prompt="Two visual directions for a calm productivity app icon" size=1024x1024 count=2
|
||||
```
|
||||
|
||||
编辑一张本地参考图像：
|
||||
|
||||
```text
|
||||
```
|
||||
/tool image_generate action=generate model=openai/gpt-image-2 prompt="Keep the subject, replace the background with a bright studio setup" image=/path/to/reference.png size=1024x1536
|
||||
```
|
||||
|
||||
使用多张参考图像进行编辑：
|
||||
|
||||
```text
|
||||
```
|
||||
/tool image_generate action=generate model=openai/gpt-image-2 prompt="Combine the character identity from the first image with the color palette from the second" images='["/path/to/character.png","/path/to/palette.jpg"]' size=1536x1024
|
||||
```
|
||||
|
||||
如果你希望通过 Azure OpenAI 部署而不是
|
||||
`api.openai.com` 来路由 OpenAI 图像生成，请参阅 OpenAI provider 文档中的 [Azure OpenAI 端点](/zh-CN/providers/openai#azure-openai-endpoints)。
|
||||
如果你想通过 Azure OpenAI 部署而不是 `api.openai.com` 路由 OpenAI 图像生成，请参阅 OpenAI 提供商文档中的 [Azure OpenAI endpoints](/zh-CN/providers/openai#azure-openai-endpoints)。
|
||||
|
||||
MiniMax 图像生成可通过两种内置 MiniMax 认证路径使用：
|
||||
|
||||
- API 密钥设置使用 `minimax/image-01`
|
||||
- OAuth 设置使用 `minimax-portal/image-01`
|
||||
- `minimax/image-01` 用于 API 密钥配置
|
||||
- `minimax-portal/image-01` 用于 OAuth 配置
|
||||
|
||||
## Provider 能力
|
||||
## 提供商能力
|
||||
|
||||
| 能力 | OpenAI | Google | fal | MiniMax | ComfyUI | Vydra | xAI |
|
||||
| --------------------- | ---------------------- | -------------------- | -------------------- | ------------------------- | --------------------------------- | ------- | -------------------- |
|
||||
| 生成 | 是（最多 4 张） | 是（最多 4 张） | 是（最多 4 张） | 是（最多 9 张） | 是（工作流定义的输出） | 是（1 张） | 是（最多 4 张） |
|
||||
| 编辑/参考 | 是（最多 5 张图像） | 是（最多 5 张图像） | 是（1 张图像） | 是（1 张图像，主体参考） | 是（1 张图像，由工作流配置） | 否 | 是（最多 5 张图像） |
|
||||
| 尺寸控制 | 是（最高 4K） | 是 | 是 | 否 | 否 | 否 | 否 |
|
||||
| 宽高比 | 否 | 是 | 是（仅生成） | 是 | 否 | 否 | 是 |
|
||||
| 分辨率（1K/2K/4K） | 否 | 是 | 是 | 否 | 否 | 否 | 是（1K/2K） |
|
||||
| 能力 | OpenAI | Google | fal | MiniMax | ComfyUI | Vydra | xAI |
|
||||
| --------------------- | -------------------- | -------------------- | ------------------- | -------------------------- | ---------------------------------- | ------- | -------------------- |
|
||||
| 生成 | 是（最多 4 张） | 是（最多 4 张） | 是（最多 4 张） | 是（最多 9 张） | 是（输出由工作流定义） | 是（1 张） | 是（最多 4 张） |
|
||||
| 编辑/参考 | 是（最多 5 张图像） | 是（最多 5 张图像） | 是（1 张图像） | 是（1 张图像，主体参考） | 是（1 张图像，由工作流配置） | 否 | 是（最多 5 张图像） |
|
||||
| 尺寸控制 | 是（最高 4K） | 是 | 是 | 否 | 否 | 否 | 否 |
|
||||
| 宽高比 | 否 | 是 | 是（仅生成） | 是 | 否 | 否 | 是 |
|
||||
| 分辨率（1K/2K/4K） | 否 | 是 | 是 | 否 | 否 | 否 | 是（1K/2K） |
|
||||
|
||||
### xAI `grok-imagine-image`
|
||||
|
||||
内置 xAI provider 会对纯提示请求使用 `/v1/images/generations`，
|
||||
当存在 `image` 或 `images` 时则使用 `/v1/images/edits`。
|
||||
内置 xAI 提供商在仅提示词请求时使用 `/v1/images/generations`，而在存在 `image` 或 `images` 时使用 `/v1/images/edits`。
|
||||
|
||||
- 模型：`xai/grok-imagine-image`、`xai/grok-imagine-image-pro`
|
||||
- 数量：最多 4 张
|
||||
- 参考：1 个 `image` 或最多 5 个 `images`
|
||||
- 参考：一个 `image` 或最多五个 `images`
|
||||
- 宽高比：`1:1`、`16:9`、`9:16`、`4:3`、`3:4`、`2:3`、`3:2`
|
||||
- 分辨率：`1K`、`2K`
|
||||
- 输出：作为 OpenClaw 管理的图像附件返回
|
||||
- 输出：作为由 OpenClaw 管理的图像附件返回
|
||||
|
||||
在共享的跨 provider `image_generate` 契约中，OpenClaw 有意不暴露 xAI 原生的 `quality`、`mask`、`user` 或
|
||||
其他额外的原生专有宽高比，直到这些控制项在共享契约中存在为止。
|
||||
在这些控制项出现在共享的跨提供商 `image_generate` 契约中之前，OpenClaw 有意不公开 xAI 原生的 `quality`、`mask`、`user` 或其他仅原生支持的宽高比选项。
|
||||
|
||||
## 相关内容
|
||||
|
||||
- [工具概览](/zh-CN/tools) —— 所有可用的智能体工具
|
||||
- [fal](/zh-CN/providers/fal) —— fal 图像与视频 provider 设置
|
||||
- [ComfyUI](/zh-CN/providers/comfy) —— 本地 ComfyUI 与 Comfy Cloud 工作流设置
|
||||
- [Google（Gemini）](/zh-CN/providers/google) —— Gemini 图像 provider 设置
|
||||
- [MiniMax](/zh-CN/providers/minimax) —— MiniMax 图像 provider 设置
|
||||
- [OpenAI](/zh-CN/providers/openai) —— OpenAI Images provider 设置
|
||||
- [Vydra](/zh-CN/providers/vydra) —— Vydra 图像、视频与语音设置
|
||||
- [xAI](/zh-CN/providers/xai) —— Grok 图像、视频、搜索、代码执行与 TTS 设置
|
||||
- [配置参考](/zh-CN/gateway/configuration-reference#agent-defaults) —— `imageGenerationModel` 配置
|
||||
- [模型](/zh-CN/concepts/models) —— 模型配置与故障转移
|
||||
- [Tools Overview](/zh-CN/tools) — 所有可用的智能体工具
|
||||
- [fal](/zh-CN/providers/fal) — fal 图像和视频提供商设置
|
||||
- [ComfyUI](/zh-CN/providers/comfy) — 本地 ComfyUI 和 Comfy Cloud 工作流设置
|
||||
- [Google (Gemini)](/zh-CN/providers/google) — Gemini 图像提供商设置
|
||||
- [MiniMax](/zh-CN/providers/minimax) — MiniMax 图像提供商设置
|
||||
- [OpenAI](/zh-CN/providers/openai) — OpenAI Images 提供商设置
|
||||
- [Vydra](/zh-CN/providers/vydra) — Vydra 图像、视频和语音设置
|
||||
- [xAI](/zh-CN/providers/xai) — Grok 图像、视频、搜索、代码执行和 TTS 设置
|
||||
- [Configuration Reference](/zh-CN/gateway/configuration-reference#agent-defaults) — `imageGenerationModel` 配置
|
||||
- [Models](/zh-CN/concepts/models) — 模型配置和故障转移
|
||||
|
||||
Loading…
Reference in New Issue
Block a user