openclaw/docs
openclaw/docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore(i18n): refresh zh-CN translations

Browse Source
This commit is contained in:
openclaw-docs-i18n[bot] 2026-04-23 12:52:15 +00:00
parent b145862a42
commit aab101d5ea
4 changed files with 447 additions and 336 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

39
docs/zh-CN/cli/status.md
View File

@ -1,14 +1,14 @@
---
read_when:
- 你想快速诊断渠道健康状态和最近会话接收方
- 你想获取一个适合粘贴的“all”状态输出用于调试
summary: '`openclaw status` 的 CLI 参考（诊断、探测、使用情况快照）'
title: status
- 你想快速诊断渠道健康状态 + 最近会话的接收方
- 你想要一个可直接粘贴的 “all” 状态输出用于调试
summary: '`openclaw status` 的 CLI 参考（诊断、探测、用法快照）'
title: 状态
x-i18n:
generated_at: "2026-04-05T08:20:27Z"
generated_at: "2026-04-23T12:50:44Z"
model: gpt-5.4
provider: openai
source_hash: fbe9d94fbe9938cd946ee6f293b5bd3b464b75e1ade2eacdd851788c3bffe94e
source_hash: 015614e329ec172a62c625581897fa64589f12dfe28edefe8a2764b5b5367b2a
source_path: cli/status.md
workflow: 15
---
@ -24,19 +24,20 @@ openclaw status --deep
openclaw status --usage
```
说明：
注意：
- `--deep` 会运行实时探测（WhatsApp Web + Telegram + Discord + Slack + Signal）。
- `--usage` 会以 `X% left` 的形式打印规范化后的提供商使用窗口。
- MiniMax 的原始 `usage_percent` / `usagePercent` 字段表示剩余额度，因此 OpenClaw 会在显示前对其取反。若存在基于计数的字段，则优先使用。对于 `model_remains` 响应，会优先使用聊天模型条目，必要时根据时间戳推导窗口标签，并在套餐标签中包含模型名称。
- 当当前会话快照信息较少时，`/status` 可以从最新的转录使用日志中回填令牌和缓存计数器。现有的非零实时值仍然优先于转录回退值。
- 当实时会话条目缺少活动运行时模型标签时，转录回退也可以恢复它。如果该转录模型与已选模型不同，status 会针对恢复出的运行时模型而不是已选模型解析上下文窗口。
- 对于 prompt 大小统计，当会话元数据缺失或更小时，转录回退会优先使用更大的、面向 prompt 的总量，这样自定义提供商会话就不会退化为显示 `0` token。
- 当配置了多个智能体时，输出会包含按智能体划分的会话存储。
- 概览在可用时会包含 Gateway 网关 + 节点宿主服务的安装/运行时状态。
- 概览会包含更新渠道 + git SHA（适用于源码检出）。
- 更新信息会显示在概览中；如果有可用更新，status 会打印运行 `openclaw update` 的提示（参见[更新](/install/updating)）。
- `--usage` 会以 `X% left` 的格式打印标准化的提供商用量窗口。
- 会话状态输出现在会将 `Runtime:` 与 `Runner:` 分开显示。`Runtime` 表示执行路径和沙箱状态（`direct`、`docker/*`），而 `Runner` 会告诉你该会话使用的是内置 Pi、基于 CLI 的提供商，还是 ACP harness 后端，例如 `codex (acp/acpx)`。
- MiniMax 的原始 `usage_percent` / `usagePercent` 字段表示剩余额度，因此 OpenClaw 会在显示前将其反转；如果存在基于计数的字段，则优先使用这些字段。`model_remains` 响应会优先选择聊天模型条目，在需要时根据时间戳推导窗口标签，并在套餐标签中包含模型名称。
- 当当前会话快照信息较少时，`/status` 可以从最近的 transcript 用量日志中回填 token 和缓存计数器。现有的非零实时值仍然优先于 transcript 回退值。
- transcript 回退还可以在实时会话条目缺少活动运行时模型标签时恢复它。如果该 transcript 模型与所选模型不同，状态会根据恢复出的运行时模型而不是所选模型来解析上下文窗口。
- 对于 prompt 大小统计，当会话元数据缺失或更小时，transcript 回退会优先使用更大的、面向 prompt 的总量，这样自定义提供商会话就不会显示为 `0` token。
- 当配置了多个智能体时，输出会包含每个智能体的会话存储。
- 概览会在可用时包含 Gateway 网关 + 节点主机服务的安装/运行状态。
- 概览会包含更新通道 + git SHA（用于源码检出）。
- 更新信息会显示在概览中；如果有可用更新，status 会打印提示，建议运行 `openclaw update`（参见[更新](/zh-CN/install/updating)）。
- 只读状态界面（`status`、`status --json`、`status --all`）会在可能的情况下，为其目标配置路径解析受支持的 SecretRef。
- 如果已配置受支持的渠道 SecretRef，但在当前命令路径中不可用，status 会保持只读，并报告降级输出，而不是崩溃。人类可读输出会显示诸如“configured token unavailable in this command path”之类的警告，JSON 输出则包含 `secretDiagnostics`。
- 当命令本地 SecretRef 解析成功时，status 会优先使用解析后的快照，并从最终输出中清除临时的“secret unavailable”渠道标记。
- `status --all` 包含一个 Secrets 概览行，以及一个诊断部分，用于汇总密钥诊断信息（为便于阅读已截断），同时不会停止报告生成。
- 如果已配置受支持的渠道 SecretRef，但在当前命令路径中不可用，status 会保持只读，并报告降级输出，而不是崩溃。人类可读输出会显示诸如“此命令路径中无法使用已配置 token”之类的警告，JSON 输出则会包含 `secretDiagnostics`。
- 当命令本地 SecretRef 解析成功时，status 会优先使用已解析的快照，并从最终输出中清除临时的“secret unavailable”渠道标记。
- `status --all` 包含一个 Secrets 概览行，以及一个诊断部分，用于汇总 Secret 诊断信息（为便于阅读会截断），同时不会停止报告生成。

312
docs/zh-CN/providers/openai.md
View File

@ -1,54 +1,54 @@
---
read_when:
- 你想在 OpenClaw 中使用 OpenAI 模型
- 你想使用 Codex 订阅认证，而不是 API 密钥
- 你想使用 Codex 订阅认证而不是 API 密钥
- 你需要更严格的 GPT-5 智能体执行行为
summary: 在 OpenClaw 中通过 API 密钥或 Codex 订阅使用 OpenAI
summary: 在 OpenClaw 中使用 OpenAI 的 API 密钥或 Codex 订阅
title: OpenAI
x-i18n:
generated_at: "2026-04-23T06:42:29Z"
generated_at: "2026-04-23T12:50:54Z"
model: gpt-5.4
provider: openai
source_hash: c3d847e53c2faee5363071dfdcb1f4150b64577674161e000844f579482198d1
source_hash: ac42660234e1971440f6de3b04adb1d3a1fddca20219fb68936c36e4c2f95265
source_path: providers/openai.md
workflow: 15
---
# OpenAI
OpenAI 提供 GPT 模型的开发者 API。OpenClaw 支持两种认证路径：
OpenAI 提供用于 GPT 模型的开发者 API。OpenClaw 支持两种认证方式：
- **API 密钥** —— 通过基于用量计费的 OpenAI Platform 直接访问（`openai/*` 模型）
- **Codex 订阅** —— 通过 ChatGPT/Codex 登录并使用订阅访问（`openai-codex/*` 模型）
- **API 密钥** — 直接访问 OpenAI Platform，并按使用量计费（`openai/*` 模型）
- **Codex 订阅** — 使用 ChatGPT/Codex 登录，并通过订阅访问（`openai-codex/*` 模型）
OpenAI 明确支持在 OpenClaw 这类外部工具和工作流中使用订阅 OAuth。
OpenAI 明确支持在 OpenClaw 这类外部工具和工作流中使用基于订阅的 OAuth。
## OpenClaw 功能覆盖范围
| OpenAI 能力 | OpenClaw 接口 | 状态 |
| OpenAI 能力 | OpenClaw 支持面 | 状态 |
| ------------------------- | ----------------------------------------- | ------------------------------------------------------ |
| Chat / Responses | `openai/<model>` 模型提供商 | 是 |
| Codex 订阅模型 | `openai-codex/<model>` 模型提供商 | 是 |
| 服务端 Web 搜索 | 原生 OpenAI Responses 工具 | 是，在启用 Web 搜索且未固定提供商时 |
| 图像 | `image_generate` | 是 |
| 视频 | `video_generate` | 是 |
| 文本转语音 | `messages.tts.provider: "openai"` / `tts` | 是 |
| 批量语音转文本 | `tools.media.audio` / 媒体理解 | 是 |
| 流式语音转文本 | Voice Call `streaming.provider: "openai"` | 是 |
| 实时语音 | Voice Call `realtime.provider: "openai"` | 是 |
| Embeddings | 记忆嵌入提供商 | 是 |
| 聊天 / Responses | `openai/<model>` 模型提供商 | 是 |
| Codex 订阅模型 | `openai-codex/<model>` 模型提供商 | 是 |
| 服务器端网页搜索 | 原生 OpenAI Responses 工具 | 是，在启用网页搜索且未固定提供商时可用 |
| 图像 | `image_generate` | 是 |
| 视频 | `video_generate` | 是 |
| 文本转语音 | `messages.tts.provider: "openai"` / `tts` | 是 |
| 批量语音转文本 | `tools.media.audio` / 媒体理解 | 是 |
| 流式语音转文本 | Voice Call `streaming.provider: "openai"` | 是 |
| 实时语音 | Voice Call `realtime.provider: "openai"` | 是 |
| Embeddings | memory 嵌入提供商 | 是 |
## 入门指南
选择你偏好的认证方式，并按步骤进行设置。
选择你偏好的认证方式，并按照设置步骤操作。
<Tabs>
<Tab title="API 密钥（OpenAI Platform）">
**最适合：** 直接 API 访问和基于用量的计费。
**最适合：** 直接 API 访问和按使用量计费。
<Steps>
<Step title="获取你的 API 密钥">
在 [OpenAI Platform dashboard](https://platform.openai.com/api-keys) 创建或复制一个 API 密钥。
在 [OpenAI Platform 控制台](https://platform.openai.com/api-keys) 创建或复制一个 API 密钥。
</Step>
<Step title="运行新手引导">
```bash
@ -95,7 +95,7 @@ x-i18n:
</Tab>
<Tab title="Codex 订阅">
**最适合：** 使用你的 ChatGPT/Codex 订阅，而不是单独的 API 密钥。Codex cloud 需要 ChatGPT 登录。
**最适合：** 使用你的 ChatGPT/Codex 订阅，而不是单独的 API 密钥。Codex cloud 需要使用 ChatGPT 登录。
<Steps>
<Step title="运行 Codex OAuth">
@ -109,7 +109,7 @@ x-i18n:
openclaw models auth login --provider openai-codex
```
对于无头环境或不适合回调的环境，可添加 `--device-code`，通过 ChatGPT 设备码流程登录，而不是使用 localhost 浏览器回调：
对于无头环境或不适合回调的设置，可添加 `--device-code`，使用 ChatGPT 的设备码流程登录，而不是 localhost 浏览器回调：
```bash
openclaw models auth login --provider openai-codex --device-code
@ -132,10 +132,10 @@ x-i18n:
| 模型引用 | 路由 | 认证 |
|-----------|-------|------|
| `openai-codex/gpt-5.4` | ChatGPT/Codex OAuth | Codex 登录 |
| `openai-codex/gpt-5.3-codex-spark` | ChatGPT/Codex OAuth | Codex 登录（取决于 entitlement） |
| `openai-codex/gpt-5.3-codex-spark` | ChatGPT/Codex OAuth | Codex 登录（取决于权限） |
<Note>
此路由有意与 `openai/gpt-5.4` 分开。若要直接访问 Platform，请将 API 密钥用于 `openai/*`；若要使用 Codex 订阅访问，请使用 `openai-codex/*`。
该路由刻意与 `openai/gpt-5.4` 分开。要直接访问 Platform，请使用带 API 密钥的 `openai/*`；要使用 Codex 订阅访问，请使用 `openai-codex/*`。
</Note>
### 配置示例
@ -147,19 +147,19 @@ x-i18n:
```
<Note>
新手引导不再从 `~/.codex` 导入 OAuth 材料。请使用浏览器 OAuth（默认）或上面的设备码流程登录 —— OpenClaw 会在它自己的智能体认证存储中管理生成的凭证。
新手引导不再从 `~/.codex` 导入 OAuth 材料。请使用浏览器 OAuth（默认）或上面的设备码流程登录——OpenClaw 会在它自己的智能体认证存储中管理生成的凭证。
</Note>
### 上下文窗口上限
OpenClaw 将模型元数据与运行时上下文上限视为两个独立的值。
OpenClaw 将模型元数据和运行时上下文上限视为两个独立的值。
对于 `openai-codex/gpt-5.4`：
- 原生 `contextWindow`：`1050000`
- 默认运行时 `contextTokens` 上限：`272000`
实践中，较小的默认上限通常具有更好的延迟和质量特性。你可以通过 `contextTokens` 覆盖它：
较小的默认上限在实践中具有更好的延迟和质量表现。你可以用 `contextTokens` 覆盖它：
```json5
{
@ -186,11 +186,11 @@ x-i18n:
| 能力 | 值 |
| ------------------------- | ---------------------------------- |
| 默认模型 | `openai/gpt-image-2` |
| 每次请求的最大图像数 | 4 |
| 编辑模式 | 已启用（最多 5 张参考图像） |
| 尺寸覆盖 | 支持，包括 2K/4K 尺寸 |
| 宽高比 / 分辨率 | 不会转发到 OpenAI Images API |
| 默认模型 | `openai/gpt-image-2` |
| 每次请求的最大图像数 | 4 |
| 编辑模式 | 已启用（最多 5 张参考图像） |
| 尺寸覆盖 | 支持，包括 2K/4K 尺寸 |
| 宽高比 / 分辨率 | 不会转发给 OpenAI Images API |
```json5
{
@ -203,22 +203,21 @@ x-i18n:
```
<Note>
有关共享工具参数、提供商选择和故障转移行为，请参见 [Image Generation](/zh-CN/tools/image-generation)。
有关共享工具参数、提供商选择和故障切换行为，请参阅 [图像生成](/zh-CN/tools/image-generation)。
</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`。
生成：
```
/tool image_generate model=openai/gpt-image-2 prompt="为 OpenClaw 在 macOS 上发布制作一张精致的启动海报" size=3840x2160 count=1
/tool image_generate model=openai/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="保留物体形状，将材质改为半透明玻璃" image=/path/to/reference.png size=1024x1536
/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
```
## 视频生成
@ -227,11 +226,11 @@ x-i18n:
| 能力 | 值 |
| ---------------- | --------------------------------------------------------------------------------- |
| 默认模型 | `openai/sora-2` |
| 模式 | 文本生成视频、图像生成视频、单视频编辑 |
| 参考输入 | 1 张图像或 1 个视频 |
| 尺寸覆盖 | 支持 |
| 其他覆盖 | `aspectRatio`、`resolution`、`audio`、`watermark` 会被忽略，并给出工具警告 |
| 默认模型 | `openai/sora-2` |
| 模式 | 文生视频、图生视频、单视频编辑 |
| 参考输入 | 1 张图像或 1 个视频 |
| 尺寸覆盖 | 支持 |
| 其他覆盖 | `aspectRatio`、`resolution`、`audio`、`watermark` 会被忽略，并显示工具警告 |
```json5
{
@ -244,22 +243,22 @@ x-i18n:
```
<Note>
有关共享工具参数、提供商选择和故障转移行为，请参见 [Video Generation](/zh-CN/tools/video-generation)。
有关共享工具参数、提供商选择和故障切换行为，请参阅 [视频生成](/zh-CN/tools/video-generation)。
</Note>
## GPT-5 提示词贡献
OpenClaw 会为跨提供商的 GPT-5 系列运行添加一个共享的 GPT-5 提示词贡献。它按模型 ID 应用，因此 `openai/gpt-5.4`、`openai-codex/gpt-5.4`、`openrouter/openai/gpt-5.4`、`opencode/gpt-5.4` 以及其他兼容的 GPT-5 引用都会获得同一层覆盖。较早的 GPT-4.x 模型则不会。
OpenClaw 为跨提供商的 GPT-5 系列运行添加了共享的 GPT-5 提示词贡献。它按模型 id 生效，因此 `openai/gpt-5.4`、`openai-codex/gpt-5.4`、`openrouter/openai/gpt-5.4`、`opencode/gpt-5.4` 以及其他兼容的 GPT-5 引用都会接收相同的覆盖层。较旧的 GPT-4.x 模型则不会。
内置的原生 Codex harness 提供商（`codex/*`）通过 Codex app-server 开发者指令使用相同的 GPT-5 行为和心跳覆盖，因此 `codex/gpt-5.x` 会话即使其余 harness 提示词由 Codex 自行管理，也会保持相同的执行跟进和主动心跳指导。
内置的原生 Codex harness 提供商（`codex/*`）通过 Codex app-server 开发者指令使用相同的 GPT-5 行为和 heartbeat 覆盖层，因此即使其余 harness 提示词由 Codex 自行控制，`codex/gpt-5.x` 会话仍会保持相同的后续跟进和主动 heartbeat 指导。
GPT-5 贡献为人设持久性、执行安全、工具纪律、输出形状、完成检查和验证添加了一个带标签的行为契约。渠道特定的回复和静默消息行为仍保留在共享的 OpenClaw 系统提示词和出站投递策略中。对于匹配的模型，GPT-5 指导始终启用。友好交互风格层是单独的，并且可配置。
GPT-5 贡献增加了一个带标签的行为契约，用于定义 persona 持续性、执行安全性、工具纪律、输出形状、完成检查和验证。特定于渠道的回复和静默消息行为仍保留在共享的 OpenClaw 系统提示词和出站传递策略中。对于匹配的模型，GPT-5 指导始终启用。友好的交互风格层则是独立且可配置的。
| 值 | 效果 |
| ---------------------- | ------------------------------------------- |
| `"friendly"`（默认） | 启用友好交互风格层 |
| `"on"` | `"friendly"` 的别名 |
| `"off"` | 仅禁用友好风格层 |
| `"friendly"`（默认） | 启用友好的交互风格层 |
| `"on"` | `"friendly"` 的别名 |
| `"off"` | 仅禁用友好风格层 |
<Tabs>
<Tab title="配置">
@ -287,26 +286,26 @@ GPT-5 贡献为人设持久性、执行安全、工具纪律、输出形状、
</Tip>
<Note>
当未设置共享的 `agents.defaults.promptOverlays.gpt5.personality` 时，仍会读取旧版 `plugins.entries.openai.config.personality` 作为兼容性回退。
当共享设置 `agents.defaults.promptOverlays.gpt5.personality` 未设置时，仍会读取旧版的 `plugins.entries.openai.config.personality` 作为兼容性回退。
</Note>
## 语音与音频
## 语音与语音处理
<AccordionGroup>
<Accordion title="语音合成（TTS）">
内置的 `openai` 插件为 `messages.tts` 接口注册了语音合成功能。
内置的 `openai` 插件为 `messages.tts` 支持面注册了语音合成功能。
| 设置 | 配置路径 | 默认值 |
|---------|------------|---------|
| 模型 | `messages.tts.providers.openai.model` | `gpt-4o-mini-tts` |
| 语音 | `messages.tts.providers.openai.voice` | `coral` |
| 音色 | `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` |
| 格式 | `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
{
@ -327,17 +326,14 @@ GPT-5 贡献为人设持久性、执行安全、工具纪律、输出形状、
</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
{
@ -357,37 +353,36 @@ GPT-5 贡献为人设持久性、执行安全、工具纪律、输出形状、
}
```
当共享音频媒体配置或按次转录请求提供了语言和提示词提示时，
它们会被转发给 OpenAI。
如果通过共享音频媒体配置或单次调用的转录请求提供了语言和提示信息，这些提示会转发给 OpenAI。
</Accordion>
<Accordion title="实时转录">
内置的 `openai` 插件为 Voice Call 插件注册了实时转录。
内置的 `openai` 插件为 Voice Call 插件注册了实时转录功能。
| 设置 | 配置路径 | 默认值 |
|---------|------------|---------|
| 模型 | `plugins.entries.voice-call.config.streaming.providers.openai.model` | `gpt-4o-transcribe` |
| 语言 | `...openai.language` | （未设置） |
| 提示词 | `...openai.prompt` | （未设置） |
| 提示 | `...openai.prompt` | （未设置） |
| 静音时长 | `...openai.silenceDurationMs` | `800` |
| VAD 阈值 | `...openai.vadThreshold` | `0.5` |
| API 密钥 | `...openai.apiKey` | 回退到 `OPENAI_API_KEY` |
<Note>
使用到 `wss://api.openai.com/v1/realtime` 的 WebSocket 连接，并采用 G.711 u-law（`g711_ulaw` / `audio/pcmu`）音频。这个流式提供商用于 Voice Call 的实时转录路径；Discord 语音目前仍会录制短片段，并改用批量 `tools.media.audio` 转录路径。
使用到 `wss://api.openai.com/v1/realtime` 的 WebSocket 连接，并采用 G.711 u-law（`g711_ulaw` / `audio/pcmu`）音频。这个流式提供商用于 Voice Call 的实时转录路径；Discord 语音当前仍会记录短片段，并改用批量 `tools.media.audio` 转录路径。
</Note>
</Accordion>
<Accordion title="实时语音">
内置的 `openai` 插件为 Voice Call 插件注册了实时语音。
内置的 `openai` 插件为 Voice Call 插件注册了实时语音功能。
| 设置 | 配置路径 | 默认值 |
|---------|------------|---------|
| 模型 | `plugins.entries.voice-call.config.realtime.providers.openai.model` | `gpt-realtime` |
| 语音 | `...openai.voice` | `alloy` |
| 温度 | `...openai.temperature` | `0.8` |
| 音色 | `...openai.voice` | `alloy` |
| Temperature | `...openai.temperature` | `0.8` |
| VAD 阈值 | `...openai.vadThreshold` | `0.5` |
| 静音时长 | `...openai.silenceDurationMs` | `500` |
| API 密钥 | `...openai.apiKey` | 回退到 `OPENAI_API_KEY` |
@ -399,23 +394,134 @@ GPT-5 贡献为人设持久性、执行安全、工具纪律、输出形状、
</Accordion>
</AccordionGroup>
## Azure OpenAI 端点
内置的 `openai` 提供商可通过覆盖 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) 下的 **实时语音**
折叠面板。
</Note>
在以下情况下使用 Azure OpenAI：
- 你已经拥有 Azure OpenAI 订阅、配额或企业协议
- 你需要 Azure 提供的区域数据驻留或合规控制
- 你希望将流量保留在现有的 Azure 租户内
### 配置
如需通过内置的 `openai` 提供商使用 Azure 图像生成，请将
`models.providers.openai.baseUrl` 指向你的 Azure 资源，并将 `apiKey` 设为
Azure OpenAI 密钥（而不是 OpenAI Platform 密钥）：
```json5
{
models: {
providers: {
openai: {
baseUrl: "https://<your-resource>.openai.azure.com",
apiKey: "<azure-openai-api-key>",
},
},
},
}
```
OpenClaw 会将以下 Azure 主机后缀识别为 Azure 图像生成路由：
- `*.openai.azure.com`
- `*.services.ai.azure.com`
- `*.cognitiveservices.azure.com`
对于在已识别 Azure 主机上发起的图像生成请求，OpenClaw 会：
- 发送 `api-key` 头，而不是 `Authorization: Bearer`
- 使用按 deployment 划分的路径（`/openai/deployments/{deployment}/...`）
- 为每个请求追加 `?api-version=...`
其他 base URL（公共 OpenAI、OpenAI 兼容代理）会继续使用标准的
OpenAI 图像请求格式。
<Note>
`openai` 提供商图像生成路径的 Azure 路由要求
OpenClaw 2026.4.22 或更高版本。更早版本会将任何自定义
`openai.baseUrl` 视为公共 OpenAI 端点，因此会在 Azure
图像 deployment 上失败。
</Note>
### API 版本
设置 `AZURE_OPENAI_API_VERSION`，可为 Azure 图像生成路径固定特定的 Azure 预览版或 GA 版本：
```bash
export AZURE_OPENAI_API_VERSION="2024-12-01-preview"
```
当该变量未设置时，默认值为 `2024-12-01-preview`。
### 模型名称就是 deployment 名称
Azure OpenAI 会将模型绑定到 deployment。对于通过内置 `openai` 提供商路由的 Azure 图像生成请求，OpenClaw 中的 `model` 字段必须是你在 Azure 门户中配置的 **Azure deployment 名称**，而不是公共 OpenAI 模型 id。
如果你创建了一个名为 `gpt-image-2-prod` 的 deployment，并由它提供 `gpt-image-2`：
```
/tool image_generate model=openai/gpt-image-2-prod prompt="A clean poster" size=1024x1024 count=1
```
同样的 deployment 名称规则也适用于通过内置 `openai` 提供商路由的图像生成调用。
### 区域可用性
Azure 图像生成目前仅在部分区域可用
（例如 `eastus2`、`swedencentral`、`polandcentral`、`westus3`、
`uaenorth`）。在创建 deployment 之前，请先查看 Microsoft 的最新区域列表，并确认你的区域提供了相应的具体模型。
### 参数差异
Azure OpenAI 与公共 OpenAI 并不总是接受相同的图像参数。
Azure 可能会拒绝公共 OpenAI 允许的某些选项（例如 `gpt-image-2` 上某些
`background` 值），或者仅在特定模型版本上提供这些选项。这些差异来自 Azure 和底层模型，而不是 OpenClaw。如果 Azure 请求因验证错误而失败，请在 Azure 门户中检查你的具体 deployment 和 API 版本所支持的参数集合。
<Note>
Azure OpenAI 使用原生传输和兼容行为，但不会接收
OpenClaw 的隐藏归因头。详情请参阅 [高级配置](#advanced-configuration)
下的 **原生与 OpenAI 兼容路由**
折叠面板。
</Note>
<Tip>
如需使用单独的 Azure OpenAI Responses 提供商（不同于 `openai`
提供商），请参阅
[服务器端压缩](#server-side-compaction-responses-api) 折叠面板中的
`azure-openai-responses/*` 模型引用。
</Tip>
<Note>
Azure 聊天和 Responses 流量除了覆盖 base URL 外，还需要 Azure 特定的提供商/API 配置。如果你希望在图像生成之外使用 Azure 模型调用，请使用新手引导流程或提供商配置来设置正确的 Azure API/认证格式，而不要假设仅 `openai.baseUrl` 就足够。
</Note>
## 高级配置
<AccordionGroup>
<Accordion title="传输方式（WebSocket 与 SSE）">
对于 `openai/*` 和 `openai-codex/*`，OpenClaw 默认都采用 WebSocket 优先、SSE 回退（`"auto"`）。
对于 `openai/*` 和 `openai-codex/*`，OpenClaw 默认都使用 WebSocket 优先，并在失败时回退到 SSE（`"auto"`）。
在 `"auto"` 模式下，OpenClaw 会：
- 在回退到 SSE 之前重试一次早期 WebSocket 失败
- 在失败后，将 WebSocket 标记为约 60 秒的降级状态，并在冷却期间使用 SSE
- 在回退到 SSE 之前，重试一次早期 WebSocket 失败
- 失败后，将 WebSocket 标记为约 60 秒的降级状态，并在冷却期间使用 SSE
- 为重试和重连附加稳定的会话与轮次标识头
- 在不同传输变体间规范化用量计数器（`input_tokens` / `prompt_tokens`）
- 在不同传输变体之间标准化使用计数器（`input_tokens` / `prompt_tokens`）
| 值 | 行为 |
|-------|----------|
| `"auto"`（默认） | WebSocket 优先，SSE 回退 |
| `"sse"` | 强制仅使用 SSE |
| `"websocket"` | 强制仅使用 WebSocket |
| `"sse"` | 仅强制使用 SSE |
| `"websocket"` | 仅强制使用 WebSocket |
```json5
{
@ -432,13 +538,13 @@ GPT-5 贡献为人设持久性、执行安全、工具纪律、输出形状、
```
相关 OpenAI 文档：
- [Realtime API with WebSocket](https://platform.openai.com/docs/guides/realtime-websocket)
- [Streaming API responses (SSE)](https://platform.openai.com/docs/guides/streaming-responses)
- [使用 WebSocket 的 Realtime API](https://platform.openai.com/docs/guides/realtime-websocket)
- [流式 API 响应（SSE）](https://platform.openai.com/docs/guides/streaming-responses)
</Accordion>
<Accordion title="WebSocket 预热">
为了降低首轮延迟，OpenClaw 默认对 `openai/*` 启用 WebSocket 预热。
OpenClaw 默认对 `openai/*` 启用 WebSocket 预热，以降低首轮延迟。
```json5
// 禁用预热
@ -465,7 +571,7 @@ GPT-5 贡献为人设持久性、执行安全、工具纪律、输出形状、
- **聊天/UI：** `/fast status|on|off`
- **配置：** `agents.defaults.models["<provider>/<model>"].params.fastMode`
启用后，OpenClaw 会将快速模式映射到 OpenAI 的优先处理（`service_tier = "priority"`）。现有的 `service_tier` 值会被保留，快速模式不会改写 `reasoning` 或 `text.verbosity`。
启用后，OpenClaw 会将快速模式映射为 OpenAI 优先处理（`service_tier = "priority"`）。现有的 `service_tier` 值会保留，快速模式不会重写 `reasoning` 或 `text.verbosity`。
```json5
{
@ -481,13 +587,13 @@ GPT-5 贡献为人设持久性、执行安全、工具纪律、输出形状、
```
<Note>
会话级覆盖优先于配置。在 Sessions UI 中清除会话覆盖后，该会话会恢复为配置中的默认值。
会话级覆盖优先于配置。在 Sessions UI 中清除会话覆盖后，会话将恢复为配置的默认值。
</Note>
</Accordion>
<Accordion title="优先处理（service_tier）">
OpenAI 的 API 通过 `service_tier` 暴露优先处理能力。你可以在 OpenClaw 中按模型设置：
OpenAI 的 API 通过 `service_tier` 提供优先处理能力。你可以在 OpenClaw 中按模型设置它：
```json5
{
@ -505,21 +611,21 @@ GPT-5 贡献为人设持久性、执行安全、工具纪律、输出形状、
支持的值：`auto`、`default`、`flex`、`priority`。
<Warning>
`serviceTier` 只会被转发到原生 OpenAI 端点（`api.openai.com`）和原生 Codex 端点（`chatgpt.com/backend-api`）。如果你通过代理路由任一提供商，OpenClaw 会保持 `service_tier` 不变。
`serviceTier` 仅会转发到原生 OpenAI 端点（`api.openai.com`）和原生 Codex 端点（`chatgpt.com/backend-api`）。如果你通过代理路由任一提供商，OpenClaw 会保持 `service_tier` 不变。
</Warning>
</Accordion>
<Accordion title="服务端压缩（Responses API）">
对于直接 OpenAI Responses 模型（`api.openai.com` 上的 `openai/*`），OpenClaw 会自动启用服务端压缩：
<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
{
@ -571,12 +677,12 @@ GPT-5 贡献为人设持久性、执行安全、工具纪律、输出形状、
</Tabs>
<Note>
`responsesServerCompaction` 只控制 `context_management` 的注入。直接 OpenAI Responses 模型仍会强制 `store: true`，除非兼容性设置了 `supportsStore: false`。
`responsesServerCompaction` 仅控制 `context_management` 的注入。直接 OpenAI Responses 模型仍会强制 `store: true`，除非兼容性设置 `supportsStore: false`。
</Note>
</Accordion>
<Accordion title="严格智能体式 GPT 模式">
<Accordion title="严格智能体 GPT 模式">
对于 `openai/*` 和 `openai-codex/*` 上的 GPT-5 系列运行，OpenClaw 可以使用更严格的内嵌执行契约：
```json5
@ -590,26 +696,26 @@ GPT-5 贡献为人设持久性、执行安全、工具纪律、输出形状、
```
使用 `strict-agentic` 时，OpenClaw 会：
- 当工具操作可用时，不再将仅做计划的轮次视为成功推进
- 通过“立即执行”的引导重试该轮次
- 对实质性工作自动启用 `update_plan`
- 如果模型持续只规划不执行，则显式显示阻塞状态
- 当工具操作可用时，不再将“仅计划”的轮次视为成功进展
- 使用“立即执行”的引导重试该轮次
- 对于较重大的工作，自动启用 `update_plan`
- 如果模型持续规划而不执行，则显式显示阻塞状态
<Note>
仅适用于 OpenAI 和 Codex 的 GPT-5 系列运行。其他提供商和较旧的模型系列会保持默认行为。
仅适用于 OpenAI 和 Codex 的 GPT-5 系列运行。其他提供商和较旧的模型系列保持默认行为。
</Note>
</Accordion>
<Accordion title="原生路由与 OpenAI 兼容路由">
OpenClaw 会区别对待直接 OpenAI、Codex 和 Azure OpenAI 端点，以及通用的 OpenAI 兼容 `/v1` 代理：
<Accordion title="原生与 OpenAI 兼容路由">
OpenClaw 对直接 OpenAI、Codex 和 Azure OpenAI 端点与通用 OpenAI 兼容 `/v1` 代理采用不同处理方式：
**原生路由**（`openai/*`、`openai-codex/*`、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 兼容性、提示词缓存提示）
**代理/兼容路由：**
- 使用更宽松的兼容行为
@ -624,7 +730,7 @@ GPT-5 贡献为人设持久性、执行安全、工具纪律、输出形状、
<CardGroup cols={2}>
<Card title="模型选择" href="/zh-CN/concepts/model-providers" icon="layers">
选择提供商、模型引用和故障转移行为。
选择提供商、模型引用和故障切换行为。
</Card>
<Card title="图像生成" href="/zh-CN/tools/image-generation" icon="image">
共享图像工具参数和提供商选择。
@ -632,7 +738,7 @@ GPT-5 贡献为人设持久性、执行安全、工具纪律、输出形状、
<Card title="视频生成" href="/zh-CN/tools/video-generation" icon="video">
共享视频工具参数和提供商选择。
</Card>
<Card title="OAuth 和认证" href="/zh-CN/gateway/authentication" icon="key">
<Card title="OAuth 与认证" href="/zh-CN/gateway/authentication" icon="key">
认证细节和凭证复用规则。
</Card>
</CardGroup>

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

@ -2,21 +2,21 @@
read_when:
- 通过智能体生成图像
- 配置图像生成提供商和模型
- 了解 `image_generate` 工具参数
- 理解 `image_generate` 工具参数
summary: 使用已配置的提供商（OpenAI、Google Gemini、fal、MiniMax、ComfyUI、Vydra、xAI）生成和编辑图像
title: 图像生成
x-i18n:
generated_at: "2026-04-22T23:23:42Z"
generated_at: "2026-04-23T12:50:48Z"
model: gpt-5.4
provider: openai
source_hash: 228049c74dd3437544cda6418da665aed375c0494ef36a6927d15c28d7783bbd
source_hash: 0fbd8eda2cb0867d1426b9349f6778c231051d600ebe451534efbee0e215c871
source_path: tools/image-generation.md
workflow: 15
---
# 图像生成
`image_generate` 工具让智能体能够使用你已配置的提供商创建和编辑图像。生成的图像会作为媒体附件自动随智能体的回复一起发送。
`image_generate` 工具让智能体可以使用你配置的提供商创建和编辑图像。生成的图像会自动作为媒体附件随智能体的回复一起发送。
<Note>
只有在至少有一个图像生成提供商可用时，此工具才会出现。如果你在智能体工具中看不到 `image_generate`，请配置 `agents.defaults.imageGenerationModel` 或设置提供商 API 密钥。
@ -41,21 +41,21 @@ x-i18n:
3. 向智能体提问：_“生成一张友好的龙虾吉祥物图像。”_
智能体会自动调用 `image_generate`。无需将工具加入允许列表 —— 只要有可用提供商，它默认就会启用。
智能体会自动调用 `image_generate`。不需要工具允许列表——只要有可用提供商，它就默认启用。
## 支持的提供商
| 提供商 | 默认模型 | 编辑支持 | API 密钥 |
| -------- | -------------------------------- | ---------------------------------- | ----------------------------------------------------- |
| OpenAI | `gpt-image-2` | 是（最多 5 张图像） | `OPENAI_API_KEY` |
| 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` |
| 提供商 | 默认模型 | 编辑支持 | API 密钥 |
| ------ | -------------------------------- | ---------------------------------- | ------------------------------------------------------ |
| OpenAI | `gpt-image-2` | 是（最多 5 张图像） | `OPENAI_API_KEY` |
| 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"` 可在运行时检查可用的提供商和模型：
使用 `action: "list"` 可在运行时查看可用的提供商和模型：
```
/tool image_generate action=list
@ -63,22 +63,22 @@ x-i18n:
## 工具参数
| 参数 | 类型 | 描述 |
| 参数 | 类型 | 说明 |
| ------------- | -------- | ------------------------------------------------------------------------------------- |
| `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 | 输出文件名提示 |
| `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 | 输出文件名提示 |
并非所有提供商都支持所有参数。当回退提供商支持接近的几何选项而不是你精确请求的选项时，OpenClaw 会在提交前重映射到最接近的受支持尺寸、宽高比或分辨率。真正不受支持的覆盖值仍会在工具结果中报告。
并非所有提供商都支持全部参数。当回退提供商支持接近的几何选项而不是精确请求值时，OpenClaw 会在提交前重映射为最接近的受支持尺寸、宽高比或分辨率。真正不受支持的覆盖项仍会在工具结果中报告。
工具结果会报告实际应用的设置。当 OpenClaw 在提供商回退期间重映射几何参数时，返回的 `size`、`aspectRatio` 和 `resolution` 值反映的是实际发送的内容，而 `details.normalization` 会记录从请求值到应用值的转换。
工具结果会报告实际应用的设置。当 OpenClaw 在提供商回退期间重映射几何参数时，返回的 `size`、`aspectRatio` 和 `resolution` 值会反映实际发送的内容，而 `details.normalization` 会记录从请求值到应用值的转换。
## 配置
@ -104,47 +104,53 @@ x-i18n:
1. 工具调用中的 **`model` 参数**（如果智能体指定了）
2. 配置中的 **`imageGenerationModel.primary`**
3. 按顺序使用 **`imageGenerationModel.fallbacks`**
4. **自动检测** —— 仅使用基于凭证可用的提供商默认值：
4. **自动检测**——仅使用有凭证支持的提供商默认值：
- 先使用当前默认提供商
- 再按提供商 id 顺序使用其余已注册的图像生成提供商
- 再按提供商 ID 顺序使用其余已注册图像生成提供商
如果某个提供商失败（凭证错误、速率限制等），系统会自动尝试下一个候选项。如果全部失败，错误中会包含每次尝试的详细信息。
如果某个提供商失败（凭证错误、速率限制等），会自动尝试下一个候选项。如果全部失败，错误中会包含每次尝试的详细信息。
说明：
- 自动检测会感知凭证状态。只有当 OpenClaw 实际能够对某个提供商完成身份验证时，该提供商默认值才会进入候选列表。
- 自动检测默认启用。如果你希望图像生成仅使用显式设置的 `model`、`primary` 和 `fallbacks` 条目，请设置 `agents.defaults.mediaGenerationAutoProviderFallback: false`。
- 使用 `action: "list"` 可检查当前已注册的提供商、它们的默认模型以及凭证环境变量提示。
- 自动检测会感知认证状态。只有当 OpenClaw 实际能够验证该提供商时，提供商默认值才会进入候选列表。
- 自动检测默认启用。如果你希望图像生成仅使用显式的 `model`、`primary` 和 `fallbacks` 条目，请设置
`agents.defaults.mediaGenerationAutoProviderFallback: false`。
- 使用 `action: "list"` 可查看当前已注册的提供商、它们的默认模型以及认证环境变量提示。
### 图像编辑
OpenAI、Google、fal、MiniMax、ComfyUI 和 xAI 支持编辑参考图像。传入参考图像路径或 URL：
```
"生成这张照片的水彩版本" + image: "/path/to/photo.jpg"
"Generate a watercolor version of this photo" + 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/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`，否则工具会将它们报告为被忽略的覆盖项。
生成 1 张 4K 横向图像：
生成一张 4K 横向图像：
```
/tool image_generate action=generate model=openai/gpt-image-2 prompt="A clean editorial poster for OpenClaw image generation" size=3840x2160 count=1
```
生成 2 张方形图像：
生成两张方形图像：
```
/tool image_generate action=generate model=openai/gpt-image-2 prompt="Two visual directions for a calm productivity app icon" size=1024x1024 count=2
```
编辑 1 张本地参考图像：
编辑一张本地参考图像：
```
/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
@ -156,43 +162,47 @@ OpenAI 图像生成默认使用 `openai/gpt-image-2`。较旧的 `openai/gpt-ima
/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
```
MiniMax 图像生成功能可通过以下两种内置的 MiniMax 凭证路径使用：
如果要通过 Azure OpenAI 部署来路由 OpenAI 图像生成，而不是使用
`api.openai.com`，请参阅 OpenAI 提供商文档中的 [Azure OpenAI endpoints](/zh-CN/providers/openai#azure-openai-endpoints)。
- `minimax/image-01`，用于 API 密钥配置
- `minimax-portal/image-01`，用于 OAuth 配置
MiniMax 图像生成可通过两种内置的 MiniMax 认证路径使用：
- `minimax/image-01` 用于 API 密钥配置
- `minimax-portal/image-01` 用于 OAuth 配置
## 提供商能力
| 能力 | OpenAI | Google | fal | MiniMax | ComfyUI | Vydra | xAI |
| 能力 | 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） |
| 生成 | 是（最多 4 张） | 是（最多 4 张） | 是（最多 4 张） | 是（最多 9 张） | 是（输出由工作流定义） | 是（1 张） | 是（最多 4 张） |
| 编辑/参考 | 是（最多 5 张图像） | 是（最多 5 张图像） | 是（1 张图像） | 是（1 张图像，主体参考） | 是（1 张图像，由工作流配置） | 否 | 是（最多 5 张图像） |
| 尺寸控制 | 是（最高 4K） | 是 | 是 | 否 | 否 | 否 | 否 |
| 宽高比 | 否 | 是 | 是（仅生成） | 是 | 否 | 否 | 是 |
| 分辨率（1K/2K/4K） | 否 | 是 | 是 | 否 | 否 | 否 | 是（1K/2K） |
### xAI `grok-imagine-image`
内置的 xAI 提供商在仅提示词请求时使用 `/v1/images/generations`，而在存在 `image` 或 `images` 时使用 `/v1/images/edits`。
内置的 xAI 提供商在纯提示词请求时使用 `/v1/images/generations`，
当存在 `image` 或 `images` 时使用 `/v1/images/edits`。
- 模型：`xai/grok-imagine-image`、`xai/grok-imagine-image-pro`
- 数量：最多 4 张
- 参考图：单个 `image` 或最多 5 个 `images`
- 参考图像：一个 `image` 或最多五个 `images`
- 宽高比：`1:1`、`16:9`、`9:16`、`4:3`、`3:4`、`2:3`、`3:2`
- 分辨率：`1K`、`2K`
- 输出：作为由 OpenClaw 管理的图像附件返回
- 输出：以 OpenClaw 管理的图像附件形式返回
OpenClaw 有意不暴露 xAI 原生的 `quality`、`mask`、`user` 或其他仅原生支持的宽高比，除非这些控制项已经存在于共享的跨提供商 `image_generate` 合约中。
在这些控制项进入共享的跨提供商 `image_generate` 协议之前，OpenClaw 有意不暴露 xAI 原生的 `quality`、`mask`、`user` 或额外的仅原生支持宽高比。
## 相关内容
- [工具概览](/zh-CN/tools) — 所有可用的智能体工具
- [fal](/zh-CN/providers/fal) — fal 图像与视频提供商设置
- [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 设置
- [配置参考](/zh-CN/gateway/configuration-reference#agent-defaults) — `imageGenerationModel` 配置
- [模型](/zh-CN/concepts/models) — 模型配置与故障切换
- [Configuration Reference](/zh-CN/gateway/configuration-reference#agent-defaults) — `imageGenerationModel` 配置
- [Models](/zh-CN/concepts/models) — 模型配置和故障切换

306
docs/zh-CN/tools/slash-commands.md
View File

@ -5,32 +5,31 @@ read_when:
summary: 斜杠命令：文本与原生、配置以及支持的命令
title: 斜杠命令
x-i18n:
generated_at: "2026-04-23T07:06:41Z"
generated_at: "2026-04-23T12:50:41Z"
model: gpt-5.4
provider: openai
source_hash: 0f6b454afa77cf02b2c307efcc99ef35d002cb560c427affaf03ac12b2b666e8
source_hash: 13290dcdf649ae66603a92a0aca68460bb63ff476179cc2dded796aaa841d66c
source_path: tools/slash-commands.md
workflow: 15
---
# 斜杠命令
命令由 Gateway 网关处理。大多数命令必须作为**独立**消息发送，并且以 `/` 开头。
仅主机可用的 bash 聊天命令使用 `! <cmd>`（`/bash <cmd>` 是其别名）。
命令由 Gateway 网关处理。大多数命令必须作为以 `/` 开头的**独立**消息发送。
仅主机可用的 bash 聊天命令使用 `! <cmd>`（`/bash <cmd>` 是别名）。
这里有两个相关系统：
- **命令**：独立的 `/...` 消息。
- **指令**：`/think`、`/fast`、`/verbose`、`/trace`、`/reasoning`、`/elevated`、`/exec`、`/model`、`/queue`。
- 指令会在模型看到消息前被剥离。
- 在普通聊天消息中（非纯指令消息），它们会被视为“内联提示”，并且**不会**持久化会话设置。
- 在纯指令消息中（消息仅包含指令），它们会持久化到会话，并回复一条确认信息。
- 指令仅对**已授权发送者**生效。如果设置了 `commands.allowFrom`，它就是唯一使用的
allowlist；否则授权来源于渠道 allowlist/配对，以及 `commands.useAccessGroups`。
- 指令会在模型看到消息之前从消息中剥离。
- 在普通聊天消息中（不是仅含指令的消息），它们会被视为“内联提示”，且**不会**持久化会话设置。
- 在仅含指令的消息中（消息只包含指令），它们会持久化到会话，并回复一条确认信息。
- 指令只会对**已授权发送者**生效。如果设置了 `commands.allowFrom`，它就是唯一使用的允许列表；否则授权来自渠道允许列表/配对以及 `commands.useAccessGroups`。
未授权发送者看到的指令会被当作普通文本处理。
还有一些**内联快捷方式**（仅 allowlist/已授权发送者可用）：`/help`、`/commands`、`/status`、`/whoami`（`/id`）。
它们会立即运行，在模型看到消息前被剥离，剩余文本则继续按正常流程处理。
还有一些**内联快捷方式**（仅限允许列表内/已授权发送者）：`/help`、`/commands`、`/status`、`/whoami`（`/id`）。
它们会立即运行，在模型看到消息之前被剥离，剩余文本则继续走正常流程。
## 配置
@ -60,88 +59,86 @@ x-i18n:
```
- `commands.text`（默认 `true`）启用在聊天消息中解析 `/...`。
- 在没有原生命令的界面上（WhatsApp/WebChat/Signal/iMessage/Google Chat/Microsoft Teams），即使你将其设置为 `false`，文本命令仍然可用。
- 在没有原生命令的界面上（WhatsApp/WebChat/Signal/iMessage/Google Chat/Microsoft Teams），即使你将其设为 `false`，文本命令仍然可用。
- `commands.native`（默认 `"auto"`）注册原生命令。
- 自动：对 Discord/Telegram 开启；对 Slack 关闭（直到你添加 slash commands）；对不支持原生命令的提供商忽略。
- 自动：对 Discord/Telegram 开启；对 Slack 关闭（直到你添加斜杠命令）；对不支持原生能力的提供商忽略。
- 设置 `channels.discord.commands.native`、`channels.telegram.commands.native` 或 `channels.slack.commands.native` 可按提供商覆盖（布尔值或 `"auto"`）。
- `false` 会在启动时清除先前在 Discord/Telegram 上注册的命令。Slack 命令由 Slack 应用管理，不会自动移除。
- `commands.nativeSkills`（默认 `"auto"`）在支持时原生注册 **skill** 命令。
- 自动：对 Discord/Telegram 开启；对 Slack 关闭（Slack 要求为每个 skill 创建一个斜杠命令）。
- `false` 会在启动时清除 Discord/Telegram 上此前已注册的命令。Slack 命令在 Slack 应用中管理，不会被自动移除。
- `commands.nativeSkills`（默认 `"auto"`）会在支持时以原生方式注册 **skill** 命令。
- 自动：对 Discord/Telegram 开启；对 Slack 关闭（Slack 需要为每个 skill 创建一个斜杠命令）。
- 设置 `channels.discord.commands.nativeSkills`、`channels.telegram.commands.nativeSkills` 或 `channels.slack.commands.nativeSkills` 可按提供商覆盖（布尔值或 `"auto"`）。
- `commands.bash`（默认 `false`）启用 `! <cmd>` 以运行主机 shell 命令（`/bash <cmd>` 是别名；需要 `tools.elevated` allowlist）。
- `commands.bashForegroundMs`（默认 `2000`）控制 bash 在切换到后台模式前等待多久（`0` 表示立即放到后台）。
- `commands.bash`（默认 `false`）启用 `! <cmd>` 来运行主机 shell 命令（`/bash <cmd>` 是别名；需要 `tools.elevated` 允许列表）。
- `commands.bashForegroundMs`（默认 `2000`）控制 bash 在切换到后台模式前等待多久（`0` 表示立即转入后台）。
- `commands.config`（默认 `false`）启用 `/config`（读取/写入 `openclaw.json`）。
- `commands.mcp`（默认 `false`）启用 `/mcp`（读取/写入由 OpenClaw 管理的 `mcp.servers` 下的 MCP 配置）。
- `commands.plugins`（默认 `false`）启用 `/plugins`（插件发现/状态，以及安装 + 启用/禁用控制）。
- `commands.plugins`（默认 `false`）启用 `/plugins`（plugin 发现/状态，以及安装 + 启用/禁用控制）。
- `commands.debug`（默认 `false`）启用 `/debug`（仅运行时覆盖）。
- `commands.restart`（默认 `true`）启用 `/restart` 以及 Gateway 网关重启工具操作。
- `commands.ownerAllowFrom`（可选）为仅限所有者的命令/工具界面设置显式所有者 allowlist。这与 `commands.allowFrom` 分开。
- 每个渠道的 `channels.<channel>.commands.enforceOwnerForCommands`（可选，默认 `false`）会使该界面上的仅限所有者命令必须由**所有者身份**运行。当为 `true` 时，发送者必须要么匹配某个已解析的所有者候选项（例如 `commands.ownerAllowFrom` 中的条目或提供商原生所有者元数据），要么在内部消息渠道上持有内部 `operator.admin` scope。渠道 `allowFrom` 中的通配符条目，或空的/无法解析的所有者候选列表，**都不足以**满足要求 —— 仅限所有者命令会在该渠道上以失败关闭的方式拒绝执行。如果你希望仅限所有者命令只受 `ownerAllowFrom` 和标准命令 allowlist 控制，请保持此项关闭。
- `commands.ownerDisplay` 控制系统提示词中所有者 id 的显示方式：`raw` 或 `hash`。
- `commands.ownerDisplaySecret` 可选设置在 `commands.ownerDisplay="hash"` 时使用的 HMAC secret。
- `commands.allowFrom`（可选）为命令授权设置按提供商划分的 allowlist。配置后，它将成为命令和指令的
唯一授权来源（渠道 allowlist/配对以及 `commands.useAccessGroups`
都会被忽略）。使用 `"*"` 作为全局默认值；提供商专用键会覆盖它。
- `commands.useAccessGroups`（默认 `true`）在未设置 `commands.allowFrom` 时，对命令强制执行 allowlist/策略。
- `commands.ownerAllowFrom`（可选）设置仅限 owner 的命令/工具界面的显式 owner 允许列表。这与 `commands.allowFrom` 分开。
- 每个渠道的 `channels.<channel>.commands.enforceOwnerForCommands`（可选，默认 `false`）会让仅限 owner 的命令在该界面上要求**owner 身份**才能运行。设为 `true` 时，发送者必须匹配已解析的 owner 候选项（例如 `commands.ownerAllowFrom` 中的条目或提供商原生 owner 元数据），或者在内部消息渠道上拥有内部 `operator.admin` 范围。渠道 `allowFrom` 中的通配符条目，或空的/无法解析的 owner 候选列表，**都不足够**——该渠道上的仅限 owner 命令会以默认拒绝方式失败。如果你希望仅限 owner 的命令只由 `ownerAllowFrom` 和标准命令允许列表控制，请保持关闭。
- `commands.ownerDisplay` 控制 owner id 在系统提示中的显示方式：`raw` 或 `hash`。
- `commands.ownerDisplaySecret` 可选地设置在 `commands.ownerDisplay="hash"` 时使用的 HMAC 密钥。
- `commands.allowFrom`（可选）设置用于命令授权的按提供商区分的允许列表。配置后，它会成为命令和指令的唯一授权来源（渠道允许列表/配对以及 `commands.useAccessGroups` 会被忽略）。使用 `"*"` 作为全局默认值；提供商专用键会覆盖它。
- `commands.useAccessGroups`（默认 `true`）在未设置 `commands.allowFrom` 时，对命令执行允许列表/策略。
## 命令列表
当前事实来源：
当前的事实来源：
- core 内置命令来自 `src/auto-reply/commands-registry.shared.ts`
- 核心内置命令来自 `src/auto-reply/commands-registry.shared.ts`
- 生成的 dock 命令来自 `src/auto-reply/commands-registry.data.ts`
- 插件命令来自插件的 `registerCommand()` 调用
- 你网关上的实际可用性仍取决于配置标志、渠道界面以及已安装/启用的插件
- plugin 命令来自 plugin 的 `registerCommand()` 调用
- 你的 Gateway 网关上的实际可用性仍取决于配置标志、渠道界面，以及已安装/已启用的 plugin
### Core 内置命令
### 核心内置命令
当前可用的内置命令：
- `/new [model]` 启动一个新会话；`/reset` 是 reset 别名。
- `/reset soft [message]` 保留当前转录，丢弃复用的 CLI 后端会话 id，并原地重新运行启动/系统提示词加载。
- `/new [model]` 启动一个新会话；`/reset` 是重置别名。
- `/reset soft [message]` 保留当前转录内容，丢弃复用的 CLI 后端会话 id，并原地重新运行启动/系统提示加载。
- `/compact [instructions]` 压缩会话上下文。参见 [/concepts/compaction](/zh-CN/concepts/compaction)。
- `/stop` 中止当前运行。
- `/session idle <duration|off>` 和 `/session max-age <duration|off>` 管理线程绑定过期时间。
- `/think <level>` 设置思考级别。可选项来自当前模型的提供商 profile；常见级别有 `off`、`minimal`、`low`、`medium` 和 `high`，也包括仅在支持时才有的自定义级别，如 `xhigh`、`adaptive`、`max`，或二元 `on`。别名：`/thinking`、`/t`。
- `/think <level>` 设置思考级别。可选项来自当前模型的活跃提供商配置文件；常见级别有 `off`、`minimal`、`low`、`medium` 和 `high`，也可能包含 `xhigh`、`adaptive`、`max` 或仅在支持时提供的二元 `on` 等自定义级别。别名：`/thinking`、`/t`。
- `/verbose on|off|full` 切换详细输出。别名：`/v`。
- `/trace on|off` 为当前会话切换插件 trace 输出。
- `/fast [status|on|off]` 显示或设置 fast 模式。
- `/reasoning [on|off|stream]` 切换 reasoning 可见性。别名：`/reason`。
- `/elevated [on|off|ask|full]` 切换 elevated 模式。别名：`/elev`。
- `/trace on|off` 切换当前会话的 plugin 跟踪输出。
- `/fast [status|on|off]` 显示或设置快速模式。
- `/reasoning [on|off|stream]` 切换推理可见性。别名：`/reason`。
- `/elevated [on|off|ask|full]` 切换提升模式。别名：`/elev`。
- `/exec host=<auto|sandbox|gateway|node> security=<deny|allowlist|full> ask=<off|on-miss|always> node=<id>` 显示或设置 exec 默认值。
- `/model [name|#|status]` 显示或设置模型。
- `/models [provider] [page] [limit=<n>|size=<n>|all]` 列出提供商，或列出某提供商的模型。
- `/queue <mode>` 管理队列行为（`steer`、`interrupt`、`followup`、`collect`、`steer-backlog`），以及如 `debounce:2s cap:25 drop:summarize` 之类的选项。
- `/models [provider] [page] [limit=<n>|size=<n>|all]` 列出提供商，或列出某个提供商的模型。
- `/queue <mode>` 管理队列行为（`steer`、`interrupt`、`followup`、`collect`、`steer-backlog`），以及诸如 `debounce:2s cap:25 drop:summarize` 之类的选项。
- `/help` 显示简短帮助摘要。
- `/commands` 显示生成的命令目录。
- `/tools [compact|verbose]` 显示当前智能体现在可用的能力。
- `/status` 显示运行时状态，包括可用时的提供商使用量/配额。
- `/tools [compact|verbose]` 显示当前智能体此刻可用的能力。
- `/status` 显示运行时状态，包括 `Runtime`/`Runner` 标签，以及可用时的提供商使用情况/配额。
- `/tasks` 列出当前会话中活跃/最近的后台任务。
- `/context [list|detail|json]` 解释上下文是如何组装的。
- `/context [list|detail|json]` 说明上下文是如何组装的。
- `/export-session [path]` 将当前会话导出为 HTML。别名：`/export`。
- `/export-trajectory [path]` 为当前会话导出一个 JSONL [trajectory bundle](/zh-CN/tools/trajectory)。别名：`/trajectory`。
- `/export-trajectory [path]` 为当前会话导出 JSONL [trajectory bundle](/zh-CN/tools/trajectory)。别名：`/trajectory`。
- `/whoami` 显示你的发送者 id。别名：`/id`。
- `/skill <name> [input]` 按名称运行一个 skill。
- `/allowlist [list|add|remove] ...` 管理 allowlist 条目。仅文本。
- `/allowlist [list|add|remove] ...` 管理允许列表条目。仅文本。
- `/approve <id> <decision>` 处理 exec 审批提示。
- `/btw <question>` 提出一个旁路问题，而不会改变未来的会话上下文。参见 [/tools/btw](/zh-CN/tools/btw)。
- `/btw <question>` 提出一个旁支问题，而不改变后续会话上下文。参见 [/tools/btw](/zh-CN/tools/btw)。
- `/subagents list|kill|log|info|send|steer|spawn` 管理当前会话的子智能体运行。
- `/acp spawn|cancel|steer|close|sessions|status|set-mode|set|cwd|permissions|timeout|model|reset-options|doctor|install|help` 管理 ACP 会话和运行时选项。
- `/focus <target>` 将当前 Discord 线程或 Telegram topic/conversation 绑定到一个会话目标。
- `/focus <target>` 将当前 Discord 线程或 Telegram 主题/会话绑定到一个会话目标。
- `/unfocus` 移除当前绑定。
- `/agents` 列出当前会话中与线程绑定的智能体。
- `/agents` 列出当前会话中线程绑定的智能体。
- `/kill <id|#|all>` 中止一个或所有正在运行的子智能体。
- `/steer <id|#> <message>` 向一个正在运行的子智能体发送引导。别名：`/tell`。
- `/config show|get|set|unset` 读取或写入 `openclaw.json`。仅限所有者。需要 `commands.config: true`。
- `/mcp show|get|set|unset` 读取或写入 OpenClaw 管理的 `mcp.servers` 下的 MCP 服务器配置。仅限所有者。需要 `commands.mcp: true`。
- `/plugins list|inspect|show|get|install|enable|disable` 检查或修改插件状态。`/plugin` 是别名。写操作仅限所有者。需要 `commands.plugins: true`。
- `/debug show|set|unset|reset` 管理仅运行时配置覆盖。仅限所有者。需要 `commands.debug: true`。
- `/usage off|tokens|full|cost` 控制每条响应的 usage 页脚，或输出本地成本摘要。
- `/steer <id|#> <message>` 向正在运行的子智能体发送引导。别名：`/tell`。
- `/config show|get|set|unset` 读取或写入 `openclaw.json`。仅限 owner。需要 `commands.config: true`。
- `/mcp show|get|set|unset` 读取或写入 `mcp.servers` 下由 OpenClaw 管理的 MCP 服务器配置。仅限 owner。需要 `commands.mcp: true`。
- `/plugins list|inspect|show|get|install|enable|disable` 检查或修改 plugin 状态。`/plugin` 是别名。写入操作仅限 owner。需要 `commands.plugins: true`。
- `/debug show|set|unset|reset` 管理仅运行时的配置覆盖。仅限 owner。需要 `commands.debug: true`。
- `/usage off|tokens|full|cost` 控制每次响应的 usage 页脚，或打印本地成本摘要。
- `/tts on|off|status|provider|limit|summary|audio|help` 控制 TTS。参见 [/tools/tts](/zh-CN/tools/tts)。
- `/restart` 在启用时重启 OpenClaw。默认：启用；设置 `commands.restart: false` 可禁用。
- `/restart` 在启用时重启 OpenClaw。默认：启用；设置 `commands.restart: false` 可将其禁用。
- `/activation mention|always` 设置群组激活模式。
- `/send on|off|inherit` 设置发送策略。仅限所有者。
- `/bash <command>` 运行主机 shell 命令。仅文本。别名：`! <command>`。需要 `commands.bash: true` 加上 `tools.elevated` allowlist。
- `/send on|off|inherit` 设置发送策略。仅限 owner。
- `/bash <command>` 运行主机 shell 命令。仅文本。别名：`! <command>`。需要 `commands.bash: true` 以及 `tools.elevated` 允许列表。
- `!poll [sessionId]` 检查后台 bash 作业。
- `!stop [sessionId]` 停止后台 bash 作业。
@ -154,17 +151,17 @@ Dock 命令由支持原生命令的渠道插件生成。当前内置集合：
- `/dock-slack`（别名：`/dock_slack`）
- `/dock-telegram`（别名：`/dock_telegram`）
### 内置插件命令
### 内置 plugin 命令
内置插件可以添加更多斜杠命令。此仓库中当前的内置命令：
内置 plugin 可以添加更多斜杠命令。此仓库中当前的内置命令：
- `/dreaming [on|off|status|help]` 切换 memory Dreaming。参见 [Dreaming](/zh-CN/concepts/dreaming)。
- `/dreaming [on|off|status|help]` 切换记忆 Dreaming。参见 [Dreaming](/zh-CN/concepts/dreaming)。
- `/pair [qr|status|pending|approve|cleanup|notify]` 管理设备配对/设置流程。参见 [Pairing](/zh-CN/channels/pairing)。
- `/phone status|arm <camera|screen|writes|all> [duration]|disarm` 临时启用高风险手机节点命令。
- `/voice status|list [limit]|set <voiceId|name>` 管理 Talk 语音配置。在 Discord 上，原生命令名称为 `/talkvoice`。
- `/voice status|list [limit]|set <voiceId|name>` 管理 Talk 语音配置。在 Discord 上，原生命令名称是 `/talkvoice`。
- `/card ...` 发送 LINE 富卡片预设。参见 [LINE](/zh-CN/channels/line)。
- `/codex status|models|threads|resume|compact|review|account|mcp|skills` 检查并控制内置 Codex app-server harness。参见 [Codex Harness](/zh-CN/plugins/codex-harness)。
- 仅 QQBot 命令：
- `/codex status|models|threads|resume|compact|review|account|mcp|skills` 检查并控制内置 Codex 应用服务器 harness。参见 [Codex Harness](/zh-CN/plugins/codex-harness)。
- 仅 QQ Bot 的命令：
- `/bot-ping`
- `/bot-version`
- `/bot-help`
@ -173,79 +170,76 @@ Dock 命令由支持原生命令的渠道插件生成。当前内置集合：
### 动态 skill 命令
用户可调用的 Skills 也会暴露为斜杠命令：
用户可调用的 Skills 也会作为斜杠命令公开：
- `/skill <name> [input]` 始终可作为通用入口点使用。
- 当 skill/plugin 注册它们时，Skills 也可能显示为直接命令，例如 `/prose`。
- 当 skill/plugin 注册它们时，Skills 也可能作为直接命令出现，例如 `/prose`。
- 原生 skill 命令注册由 `commands.nativeSkills` 和 `channels.<provider>.commands.nativeSkills` 控制。
说明：
注意：
- 命令支持在命令和参数之间使用可选的 `:`（例如 `/think: high`、`/send: on`、`/help:`）。
- `/new <model>` 接受模型别名、`provider/model` 或提供商名称（模糊匹配）；如果没有匹配项，则该文本会被视为消息正文。
- 如需完整的提供商使用量明细，请使用 `openclaw status --usage`。
- `/allowlist add|remove` 需要 `commands.config=true`，并遵循渠道的 `configWrites`。
- 在多账户渠道中，面向配置目标的 `/allowlist --account <id>` 和 `/config set channels.<provider>.accounts.<id>...` 也会遵循目标账户的 `configWrites`。
- `/usage` 控制每条响应的 usage 页脚；`/usage cost` 会根据 OpenClaw 会话日志输出本地成本摘要。
- `/restart` 默认启用；设置 `commands.restart: false` 可禁用。
- `/plugins install <spec>` 接受与 `openclaw plugins install` 相同的插件 spec：本地路径/归档、npm 包或 `clawhub:<pkg>`。
- `/plugins enable|disable` 会更新插件配置，并且可能提示需要重启。
- 仅 Discord 的原生命令：`/vc join|leave|status` 用于控制语音频道（需要 `channels.discord.voice` 和原生命令；不提供文本版本）。
- Discord 线程绑定命令（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`）要求有效启用线程绑定（`session.threadBindings.enabled` 和/或 `channels.discord.threadBindings.enabled`）。
- ACP 命令参考与运行时行为： [ACP Agents](/zh-CN/tools/acp-agents)。
- `/verbose` 用于调试和获取更多可见性；正常使用时请保持 **关闭**。
- `/trace` 比 `/verbose` 更窄：它只显示插件拥有的 trace/debug 行，并保持普通详细工具输出关闭。
- `/fast on|off` 会持久化一个会话级覆盖。使用 Sessions UI 中的 `inherit` 选项可清除此覆盖并回退到配置默认值。
- `/fast` 具有提供商特定行为：OpenAI/OpenAI Codex 会在原生 Responses 端点上将其映射为 `service_tier=priority`，而直接发送到 `api.anthropic.com` 的公开 Anthropic 请求（包括经 OAuth 认证的流量）则会将其映射为 `service_tier=auto` 或 `standard_only`。参见 [OpenAI](/zh-CN/providers/openai) 和 [Anthropic](/zh-CN/providers/anthropic)。
- 工具失败摘要仍会在相关时显示，但详细失败文本仅在 `/verbose` 为 `on` 或 `full` 时包含。
- `/reasoning`、`/verbose` 和 `/trace` 在群组环境中存在风险：它们可能暴露你原本不打算公开的内部推理、工具输出或插件诊断信息。建议保持关闭，尤其是在群聊中。
- 命令接受一个可选的 `:`，放在命令和参数之间（例如 `/think: high`、`/send: on`、`/help:`）。
- `/new <model>` 接受模型别名、`provider/model` 或提供商名称（模糊匹配）；如果没有匹配项，文本会被视为消息正文。
- 如需查看完整的提供商 usage 明细，请使用 `openclaw status --usage`。
- `/allowlist add|remove` 需要 `commands.config=true`，并遵循渠道 `configWrites`。
- 在多账号渠道中，面向配置目标的 `/allowlist --account <id>` 和 `/config set channels.<provider>.accounts.<id>...` 也会遵循目标账号的 `configWrites`。
- `/usage` 控制每次响应的 usage 页脚；`/usage cost` 会根据 OpenClaw 会话日志输出本地成本摘要。
- `/restart` 默认启用；设置 `commands.restart: false` 可禁用它。
- `/plugins install <spec>` 接受与 `openclaw plugins install` 相同的 plugin 规格：本地路径/归档、npm 包，或 `clawhub:<pkg>`。
- `/plugins enable|disable` 会更新 plugin 配置，并且可能提示你重启。
- 仅限 Discord 的原生命令：`/vc join|leave|status` 用于控制语音频道（需要 `channels.discord.voice` 和原生命令；不提供文本形式）。
- Discord 线程绑定命令（`/focus`、`/unfocus`、`/agents`、`/session idle`、`/session max-age`）要求实际线程绑定已启用（`session.threadBindings.enabled` 和/或 `channels.discord.threadBindings.enabled`）。
- ACP 命令参考和运行时行为： [ACP Agents](/zh-CN/tools/acp-agents)。
- `/verbose` 旨在用于调试和额外可见性；正常使用时请保持**关闭**。
- `/trace` 比 `/verbose` 更窄：它只显示由 plugin 拥有的 trace/debug 行，并保持普通详细工具输出关闭。
- `/fast on|off` 会持久化一个会话级覆盖。使用 Sessions UI 中的 `inherit` 选项可清除它，并回退到配置默认值。
- `/fast` 是提供商特定的：OpenAI/OpenAI Codex 会在原生 Responses 端点上映射为 `service_tier=priority`，而直接发送到 `api.anthropic.com` 的公开 Anthropic 请求（包括使用 OAuth 身份验证的流量）会映射为 `service_tier=auto` 或 `standard_only`。参见 [OpenAI](/zh-CN/providers/openai) 和 [Anthropic](/zh-CN/providers/anthropic)。
- 相关时仍会显示工具失败摘要，但详细失败文本仅在 `/verbose` 为 `on` 或 `full` 时才包含。
- `/reasoning`、`/verbose` 和 `/trace` 在群组场景中具有风险：它们可能会暴露你原本无意公开的内部推理、工具输出或 plugin 诊断信息。建议保持关闭，尤其是在群聊中。
- `/model` 会立即持久化新的会话模型。
- 如果智能体处于空闲状态，下一次运行会立即使用它。
- 如果当前已有运行中的任务，OpenClaw 会将实时切换标记为待处理，并仅在一个干净的重试点切换到新模型。
- 如果工具活动或回复输出已经开始，该待切换状态可能会一直排队，直到后续某个重试机会或下一轮用户输入。
- **快速路径：** 来自 allowlist 发送者的纯命令消息会立即处理（绕过队列 + 模型）。
- **群组提及门控：** 来自 allowlist 发送者的纯命令消息会绕过提及要求。
- **内联快捷方式（仅 allowlist 发送者）：** 某些命令嵌入在普通消息中时也可生效，并会在模型看到其余文本前被剥离。
- 示例：`hey /status` 会触发一条状态回复，而剩余文本会继续按正常流程处理。
- 当前支持：`/help`、`/commands`、`/status`、`/whoami`（`/id`）。
- 未授权的纯命令消息会被静默忽略，而内联 `/...` token 会被当作普通文本。
- **Skill 命令：** `user-invocable` Skills 会作为斜杠命令暴露。名称会被清理为 `a-z0-9_`（最长 32 个字符）；冲突名称会追加数字后缀（例如 `_2`）。
- `/skill <name> [input]` 会按名称运行一个 skill（当原生命令限制导致无法为每个 skill 提供单独命令时，这很有用）。
- 如果智能体处于空闲状态，下一次运行会立刻使用它。
- 如果某次运行已经处于活动状态，OpenClaw 会将实时切换标记为待处理，并仅在一个干净的重试点重启到新模型。
- 如果工具活动或回复输出已经开始，待处理切换可能会一直排队，直到后续的重试机会或下一个用户轮次。
- **快速路径：** 来自允许列表发送者的纯命令消息会立即处理（绕过队列 + 模型）。
- **群组提及门控：** 来自允许列表发送者的纯命令消息会绕过提及要求。
- **内联快捷方式（仅限允许列表发送者）：** 某些命令嵌入在普通消息中时也可工作，并会在模型看到剩余文本前被剥离。
- 例如：`hey /status` 会触发状态回复，而剩余文本会继续走正常流程。
- 当前包括：`/help`、`/commands`、`/status`、`/whoami`（`/id`）。
- 未授权的纯命令消息会被静默忽略，而内联 `/...` 标记会被当作普通文本。
- **Skill 命令：** `user-invocable` Skills 也会公开为斜杠命令。名称会被清洗为 `a-z0-9_`（最多 32 个字符）；冲突时会附加数字后缀（例如 `_2`）。
- `/skill <name> [input]` 按名称运行一个 skill（当原生命令限制阻止按 skill 单独创建命令时，这会很有用）。
- 默认情况下，skill 命令会作为普通请求转发给模型。
- Skills 也可选择声明 `command-dispatch: tool`，以将命令直接路由到工具（确定性、无模型）。
- 示例：`/prose`（OpenProse 插件）—— 参见 [OpenProse](/zh-CN/prose)。
- **原生命令参数：** Discord 对动态选项使用自动补全（当你省略必填参数时，也会使用按钮菜单）。Telegram 和 Slack 会在命令支持可选值且你省略参数时显示按钮菜单。
- Skills 可以选择声明 `command-dispatch: tool`，以将命令直接路由到工具（确定性，不经过模型）。
- 示例：`/prose`（OpenProse plugin）——参见 [OpenProse](/zh-CN/prose)。
- **原生命令参数：** Discord 对动态选项使用自动补全（当你省略必需参数时也会使用按钮菜单）。Telegram 和 Slack 会在命令支持选项且你省略参数时显示按钮菜单。
## `/tools`
`/tools` 回答的是一个运行时问题，而不是配置问题：**这个智能体现在在
此对话中能使用什么**。
`/tools` 回答的是一个运行时问题，而不是配置问题：**这个智能体现在在这次对话中能使用什么**。
- 默认 `/tools` 为紧凑模式，适合快速浏览。
- 默认的 `/tools` 是紧凑模式，便于快速浏览。
- `/tools verbose` 会添加简短说明。
- 支持参数的原生命令界面也会暴露相同的模式切换：`compact|verbose`。
- 结果是会话作用域的，因此更改智能体、渠道、线程、发送者授权状态或模型，都可能
改变输出。
- `/tools` 包含运行时实际可达的工具，包括 core 工具、已连接的
plugin 工具以及渠道自有工具。
- 支持参数的原生命令界面会公开相同的模式切换，即 `compact|verbose`。
- 结果是会话作用域的，因此更改智能体、渠道、线程、发送者授权或模型都可能改变输出。
- `/tools` 包含那些在运行时实际可达的工具，包括核心工具、已连接的 plugin 工具以及由渠道拥有的工具。
如需编辑 profile 和覆盖项，请使用 Control UI 的 Tools 面板或配置/目录界面，
而不要将 `/tools` 视为静态目录。
如需编辑 profile 和覆盖项，请使用 Control UI 的工具面板或配置/目录界面，而不要把 `/tools` 当作静态目录。
## Usage 界面（各处显示内容）
## Usage 界面（各处显示什么）
- **提供商 usage/配额**（例如：“Claude 剩余 80%”）会在 `/status` 中针对当前模型提供商显示，前提是已启用 usage 跟踪。OpenClaw 会将提供商窗口统一归一化为“剩余百分比”；对于 MiniMax，仅剩余百分比字段会在显示前取反，而 `model_remains` 响应会优先使用聊天模型条目以及带模型标记的套餐标签。
- `/status` 中的 **token/cache 行** 在实时会话快照信息不足时，可以回退到最近的转录 usage 条目。现有的非零实时值仍然优先，而转录回退还可以在已存储总量缺失或较小时，恢复当前活跃运行时模型标签以及更大的、以提示词为导向的总量。
- **每条响应的 token/cost** 由 `/usage off|tokens|full` 控制（附加在普通回复后）。
- `/model status` 针对的是 **模型/认证/端点**，而不是 usage。
- **提供商 usage/配额**（例如：“Claude 剩余 80%”）会在启用 usage 跟踪时显示在当前模型提供商的 `/status` 中。OpenClaw 会将提供商窗口统一为“剩余百分比”；对于 MiniMax，仅剩余值的百分比字段会在显示前反转，而 `model_remains` 响应会优先使用聊天模型条目以及带模型标签的计划标签。
- `/status` 中的**Token/cache 行**在实时会话快照信息稀少时，可以回退到最近的转录 usage 条目。现有的非零实时值仍然优先，而转录回退也可以在存储总量缺失或更小时恢复当前活动运行时模型标签以及一个更偏向 prompt 的较大总量。
- **Runtime 与 runner：** `/status` 用 `Runtime` 报告生效的执行路径和沙箱状态，用 `Runner` 报告实际运行会话的是谁：内嵌 Pi、基于 CLI 的提供商，还是 ACP harness/backend。
- **每次响应的 token/成本** 由 `/usage off|tokens|full` 控制（附加到正常回复后）。
- `/model status` 关注的是**模型/凭证/端点**，不是 usage。
## 模型选择（`/model`）
`/model` 实现为一个指令。
`/model` 被实现为一个指令。
示例：
```
```text
/model
/model list
/model 3
@ -254,20 +248,20 @@ Dock 命令由支持原生命令的渠道插件生成。当前内置集合：
/model status
```
说明：
注意：
- `/model` 和 `/model list` 会显示一个紧凑的编号选择器（模型家族 + 可用提供商）。
- 在 Discord 上，`/model` 和 `/models` 会打开一个交互式选择器，带有提供商和模型下拉框以及 Submit 步骤。
- `/model <#>` 会从该选择器中进行选择（并在可能时优先当前提供商）。
- `/model status` 会显示详细视图，包括已配置的提供商端点（`baseUrl`）和 API 模式（`api`，若可用）。
- 在 Discord 上，`/model` 和 `/models` 会打开一个交互式选择器，其中包含提供商和模型下拉框以及一个提交步骤。
- `/model <#>` 会从该选择器中选择（并在可能时优先使用当前提供商）。
- `/model status` 会显示详细视图，包括已配置的提供商端点（`baseUrl`）和 API 模式（`api`），如果可用。
## 调试覆盖项
`/debug` 允许你设置**仅运行时**的配置覆盖项（保存在内存中，不写入磁盘）。仅限所有者。默认禁用；通过 `commands.debug: true` 启用。
`/debug` 允许你设置**仅运行时**的配置覆盖项（内存中，不写磁盘）。仅限 owner。默认禁用；通过 `commands.debug: true` 启用。
示例：
```
```text
/debug show
/debug set messages.responsePrefix="[openclaw]"
/debug set channels.whatsapp.allowFrom=["+1555","+4477"]
@ -275,14 +269,14 @@ Dock 命令由支持原生命令的渠道插件生成。当前内置集合：
/debug reset
```
说明：
注意：
- 覆盖项会立即应用于新的配置读取，但**不会**写入 `openclaw.json`。
- 使用 `/debug reset` 清除所有覆盖项，并返回到磁盘上的配置。
- 覆盖项会立即应用到新的配置读取中，但**不会**写入 `openclaw.json`。
- 使用 `/debug reset` 清除所有覆盖项，并恢复到磁盘上的配置。
## 插件 trace 输出
## Plugin 跟踪输出
`/trace` 允许你切换**会话作用域的插件 trace/debug 行**，而无需打开完整 verbose 模式。
`/trace` 允许你切换**会话作用域的 plugin trace/debug 行**，而无需开启完整详细模式。
示例：
@ -292,22 +286,22 @@ Dock 命令由支持原生命令的渠道插件生成。当前内置集合：
/trace off
```
说明：
注意：
- 不带参数的 `/trace` 会显示当前会话的 trace 状态。
- `/trace on` 会为当前会话启用插件 trace 行。
- `/trace on` 会为当前会话启用 plugin trace 行。
- `/trace off` 会再次将其关闭。
- 插件 trace 行可能出现在 `/status` 中，也可能作为普通助手回复之后的一条跟进诊断消息出现。
- Plugin trace 行可能会出现在 `/status` 中，也可能作为普通助手回复之后的后续诊断消息出现。
- `/trace` 不能替代 `/debug`；`/debug` 仍用于管理仅运行时的配置覆盖项。
- `/trace` 也不能替代 `/verbose`；普通详细工具/状态输出仍归属 `/verbose`。
- `/trace` 不能替代 `/verbose`；普通的详细工具/状态输出仍属于 `/verbose`。
## 配置更新
`/config` 会写入你磁盘上的配置（`openclaw.json`）。仅限所有者。默认禁用；通过 `commands.config: true` 启用。
`/config` 会写入你的磁盘配置（`openclaw.json`）。仅限 owner。默认禁用；通过 `commands.config: true` 启用。
示例：
```
```text
/config show
/config show messages.responsePrefix
/config get messages.responsePrefix
@ -315,14 +309,14 @@ Dock 命令由支持原生命令的渠道插件生成。当前内置集合：
/config unset messages.responsePrefix
```
说明：
注意：
- 写入前会验证配置；无效更改会被拒绝。
- `/config` 更新在重启后仍会保留。
- 写入前会校验配置；无效更改会被拒绝。
- `/config` 更新会在重启后继续保留。
## MCP 更新
`/mcp` 会将 OpenClaw 管理的 MCP 服务器定义写入 `mcp.servers`。仅限所有者。默认禁用；通过 `commands.mcp: true` 启用。
`/mcp` 会将 OpenClaw 管理的 MCP 服务器定义写入 `mcp.servers` 下。仅限 owner。默认禁用；通过 `commands.mcp: true` 启用。
示例：
@ -333,14 +327,14 @@ Dock 命令由支持原生命令的渠道插件生成。当前内置集合：
/mcp unset context7
```
说明：
注意：
- `/mcp` 将配置存储在 OpenClaw 配置中，而不是 Pi 拥有的项目设置中。
- 运行时适配器决定哪些传输方式实际上可执行。
## 插件更新
## Plugin 更新
`/plugins` 允许操作员检查已发现的插件并在配置中切换启用状态。只读流程可以使用 `/plugin` 作为别名。默认禁用；通过 `commands.plugins: true` 启用。
`/plugins` 允许操作员检查已发现的 plugin，并在配置中切换启用状态。只读流程可使用 `/plugin` 作为别名。默认禁用；通过 `commands.plugins: true` 启用。
示例：
@ -352,36 +346,36 @@ Dock 命令由支持原生命令的渠道插件生成。当前内置集合：
/plugins disable context7
```
说明：
注意：
- `/plugins list` 和 `/plugins show` 会根据当前工作区和磁盘上的配置执行真实的插件发现。
- `/plugins enable|disable` 只会更新插件配置；它不会安装或卸载插件。
- 在 enable/disable 变更后，重启 Gateway 网关以应用这些更改。
- `/plugins list` 和 `/plugins show` 会基于当前工作区和磁盘配置执行真实的 plugin 发现。
- `/plugins enable|disable` 只更新 plugin 配置；不会安装或卸载 plugin。
- 在启用/禁用变更后，重启 Gateway 网关以使其生效。
## 界面说明
- **文本命令** 运行在正常聊天会话中（私信共享 `main`，群组拥有自己的会话）。
- **文本命令** 在普通聊天会话中运行（私信共享 `main`，群组有各自的会话）。
- **原生命令** 使用隔离会话：
- Discord：`agent:<agentId>:discord:slash:<userId>`
- Slack：`agent:<agentId>:slack:slash:<userId>`（前缀可通过 `channels.slack.slashCommand.sessionPrefix` 配置）
- Telegram：`telegram:slash:<userId>`（通过 `CommandTargetSessionKey` 指向聊天会话）
- **`/stop`** 会针对当前活跃聊天会话，以便中止当前运行。
- **Slack：** `channels.slack.slashCommand` 仍支持单个 `/openclaw` 风格命令。如果你启用了 `commands.native`，则必须为每个内置命令创建一个 Slack 斜杠命令（名称与 `/help` 相同）。Slack 的命令参数菜单以临时 Block Kit 按钮形式传递。
- Slack 原生命令例外：注册 `/agentstatus`（而不是 `/status`），因为 Slack 保留了 `/status`。文本 `/status` 在 Slack 消息中仍可使用。
- Telegram：`telegram:slash:<userId>`（通过 `CommandTargetSessionKey` 定位到聊天会话）
- **`/stop`** 面向当前活动聊天会话，因此它可以中止当前运行。
- **Slack：** `channels.slack.slashCommand` 仍然支持单个 `/openclaw` 风格的命令。如果你启用 `commands.native`，则必须为每个内置命令创建一个 Slack 斜杠命令（名称与 `/help` 相同）。Slack 的命令参数菜单会以临时的 Block Kit 按钮形式提供。
- Slack 原生命令例外：请注册 `/agentstatus`（而不是 `/status`），因为 Slack 保留了 `/status`。文本形式的 `/status` 在 Slack 消息中仍然可用。
## BTW 旁路问题
## BTW 旁支问题
`/btw` 是一个关于当前会话的快速**旁路问题**。
`/btw` 是一个关于当前会话的快速**旁支问题**。
与普通聊天不同：
- 它会使用当前会话作为背景上下文，
- 它会作为一次独立的**无工具**单次调用运行，
- 它不会改变未来的会话上下文，
- 它会作为一个独立的**无工具**一次性调用运行，
- 它不会改变后续会话上下文，
- 它不会写入转录历史，
- 它会作为实时旁路结果投递，而不是普通助手消息。
- 它会作为实时旁路结果传递，而不是普通助手消息。
这使得 `/btw` 在你希望主任务继续进行的同时，临时获取澄清信息时非常有用。
这使得 `/btw` 在你希望主任务继续进行的同时，临时获得一个澄清时非常有用。
示例：
@ -389,4 +383,4 @@ Dock 命令由支持原生命令的渠道插件生成。当前内置集合：
/btw what are we doing right now?
```
完整行为和客户端 UX 细节请参阅 [BTW Side Questions](/zh-CN/tools/btw)。
有关完整行为和客户端 UX 细节，请参见 [BTW Side Questions](/zh-CN/tools/btw)。