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-30 13:53:03 +00:00
parent 9e497e6796
commit dc6bb9736b
2 changed files with 361 additions and 373 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

363
docs/zh-CN/channels/slack.md
View File

@ -1,27 +1,27 @@
---
read_when:
- 设置 Slack 或调试 Slack 套接字/HTTP 模式
summary: Slack 设置和运行时行为（Socket 模式 + HTTP 请求 URL）
- 设置 Slack 或调试 Slack socket/HTTP 模式
summary: Slack 设置和运行时行为（Socket Mode + HTTP 请求 URL）
title: Slack
x-i18n:
generated_at: "2026-04-29T21:43:17Z"
generated_at: "2026-04-30T13:51:07Z"
model: gpt-5.5
provider: openai
source_hash: 08024bd947ddeb00a1ab3aaa3864cf31817303bbc0523902acdc539fc662e127
source_hash: 55beddb43a6b91c6853dcf053eab713322de4da5beced7c107d73e1c066fded6
source_path: channels/slack.md
workflow: 16
---
通过 Slack app 集成，可在私信和渠道中用于生产环境。默认模式是 Socket Mode；也支持 HTTP Request URLs。
可通过 Slack 应用集成用于生产环境的私信和渠道。默认模式为 Socket Mode；也支持 HTTP Request URLs。
<CardGroup cols={3}>
<Card title="Pairing" icon="link" href="/zh-CN/channels/pairing">
<Card title="配对" icon="link" href="/zh-CN/channels/pairing">
Slack 私信默认使用配对模式。
</Card>
<Card title="Slash commands" icon="terminal" href="/zh-CN/tools/slash-commands">
<Card title="Slash 命令" icon="terminal" href="/zh-CN/tools/slash-commands">
原生命令行为和命令目录。
</Card>
<Card title="Channel troubleshooting" icon="wrench" href="/zh-CN/channels/troubleshooting">
<Card title="渠道故障排除" icon="wrench" href="/zh-CN/channels/troubleshooting">
跨渠道诊断和修复手册。
</Card>
</CardGroup>
@ -29,19 +29,19 @@ x-i18n:
## 快速设置
<Tabs>
<Tab title="Socket Mode (default)">
<Tab title="Socket Mode（默认）">
<Steps>
<Step title="Create a new Slack app">
在 Slack app 设置中按下 **[Create New App](https://api.slack.com/apps/new)** 按钮：
<Step title="创建新的 Slack 应用">
在 Slack 应用设置中按下 **[Create New App](https://api.slack.com/apps/new)** 按钮：
- 选择 **from a manifest**，并为你的 app 选择一个工作区
- 选择 **from a manifest**，并为你的应用选择一个工作区
- 粘贴下面的[示例清单](#manifest-and-scope-checklist)，然后继续创建
- 生成带有 `connections:write` 的 **App-Level Token**（`xapp-...`）
- 安装 app，并复制显示的 **Bot Token**（`xoxb-...`）
- 安装应用并复制显示的 **Bot Token**（`xoxb-...`）
</Step>
<Step title="Configure OpenClaw">
<Step title="配置 OpenClaw">
推荐的 SecretRef 设置：
@ -73,7 +73,7 @@ SLACK_BOT_TOKEN=xoxb-...
</Step>
<Step title="Start gateway">
<Step title="启动 Gateway 网关">
```bash
openclaw gateway
@ -86,17 +86,17 @@ openclaw gateway
<Tab title="HTTP Request URLs">
<Steps>
<Step title="Create a new Slack app">
在 Slack app 设置中按下 **[Create New App](https://api.slack.com/apps/new)** 按钮：
<Step title="创建新的 Slack 应用">
在 Slack 应用设置中按下 **[Create New App](https://api.slack.com/apps/new)** 按钮：
- 选择 **from a manifest**，并为你的 app 选择一个工作区
- 选择 **from a manifest**，并为你的应用选择一个工作区
- 粘贴[示例清单](#manifest-and-scope-checklist)，并在创建前更新 URL
- 保存用于请求验证的 **Signing Secret**
- 安装 app，并复制显示的 **Bot Token**（`xoxb-...`）
- 安装应用并复制显示的 **Bot Token**（`xoxb-...`）
</Step>
<Step title="Configure OpenClaw">
<Step title="配置 OpenClaw">
推荐的 SecretRef 设置：
@ -123,12 +123,12 @@ openclaw config patch --file ./slack.http.patch.json5
<Note>
为多账号 HTTP 使用唯一的 webhook 路径
为每个账号提供不同的 `webhookPath`（默认 `/slack/events`），这样注册就不会冲突。
为每个账号指定不同的 `webhookPath`（默认 `/slack/events`），避免注册冲突。
</Note>
</Step>
<Step title="Start gateway">
<Step title="启动 Gateway 网关">
```bash
openclaw gateway
@ -142,7 +142,7 @@ openclaw gateway
## Socket Mode 传输调优
OpenClaw 默认将 Socket Mode 的 Slack SDK 客户端 pong 超时设置为 15 秒。只有在需要针对工作区或主机进行特定调优时，才覆盖传输设置：
默认情况下，OpenClaw 会将 Socket Mode 的 Slack SDK 客户端 pong 超时设为 15 秒。仅在需要针对工作区或主机做特定调优时覆盖传输设置：
```json5
{
@ -159,11 +159,11 @@ OpenClaw 默认将 Socket Mode 的 Slack SDK 客户端 pong 超时设置为 15
}
```
仅对记录 Slack websocket pong/server-ping 超时，或运行在已知存在事件循环饥饿问题主机上的 Socket Mode 工作区使用此设置。`clientPingTimeout` 是 SDK 发送客户端 ping 后等待 pong 的时间；`serverPingTimeout` 是等待 Slack 服务器 ping 的时间。App 消息和事件仍然是应用状态，不是传输活跃度信号。
仅当 Socket Mode 工作区记录了 Slack websocket pong/server-ping 超时，或运行在已知存在事件循环饥饿的主机上时，才使用此设置。`clientPingTimeout` 是 SDK 发送客户端 ping 后等待 pong 的时间；`serverPingTimeout` 是等待 Slack 服务器 ping 的时间。应用消息和事件仍是应用状态，不是传输活性信号。
## 清单和 scope 检查清单
## 清单和范围检查清单
基础 Slack app 清单对 Socket Mode 和 HTTP Request URLs 相同。只有 `settings` 块（以及斜杠命令 `url`）不同。
基础 Slack 应用清单对于 Socket Mode 和 HTTP Request URLs 相同。只有 `settings` 块（以及 slash 命令 `url`）不同。
基础清单（Socket Mode 默认）：
@ -237,7 +237,7 @@ OpenClaw 默认将 Socket Mode 的 Slack SDK 客户端 pong 超时设置为 15
}
```
对于 **HTTP Request URLs 模式**，请将 `settings` 替换为 HTTP 变体，并为每个斜杠命令添加 `url`。需要公共 URL：
对于 **HTTP Request URLs 模式**，将 `settings` 替换为 HTTP 变体，并向每个 slash 命令添加 `url`。需要公开 URL：
```json
{
@ -269,20 +269,20 @@ OpenClaw 默认将 Socket Mode 的 Slack SDK 客户端 pong 超时设置为 15
### 其他清单设置
展示扩展上述默认值的不同功能。
提供扩展上述默认值的不同功能。
<AccordionGroup>
<Accordion title="Optional native slash commands">
<Accordion title="可选原生 slash 命令">
可以使用多个[原生斜杠命令](#commands-and-slash-behavior)来替代单个配置命令，并提供更细的差异化能力：
可以使用多个[原生 slash 命令](#commands-and-slash-behavior)，而不是一个已配置的命令；注意以下细节：
- 使用 `/agentstatus` 而不是 `/status`，因为 `/status` 命令已保留。
- 一次最多可提供 25 个斜杠命令。
- 使用 `/agentstatus` 而不是 `/status`，因为 `/status` 命令是保留命令。
- 一次最多可提供 25 个 slash 命令。
将现有 `features.slash_commands` 部分替换为[可用命令](/zh-CN/tools/slash-commands#command-list)的子集：
用[可用命令](/zh-CN/tools/slash-commands#command-list)的子集替换现有的 `features.slash_commands` 部分：
<Tabs>
<Tab title="Socket Mode (default)">
<Tab title="Socket Mode（默认）">
```json
"slash_commands": [
@ -399,7 +399,7 @@ OpenClaw 默认将 Socket Mode 的 Slack SDK 客户端 pong 超时设置为 15
</Tab>
<Tab title="HTTP Request URLs">
使用与上面 Socket Mode 相同的 `slash_commands` 列表，并向每个条目添加 `"url": "https://gateway-host.example.com/slack/events"`。示例：
使用与上方 Socket Mode 相同的 `slash_commands` 列表，并向每个条目添加 `"url": "https://gateway-host.example.com/slack/events"`。示例：
```json
"slash_commands": [
@ -422,14 +422,14 @@ OpenClaw 默认将 Socket Mode 的 Slack SDK 客户端 pong 超时设置为 15
</Tabs>
</Accordion>
<Accordion title="Optional authorship scopes (write operations)">
如果你希望传出消息使用当前智能体身份（自定义用户名和图标），而不是默认 Slack app 身份，请添加 `chat:write.customize` 机器人 scope。
<Accordion title="可选作者身份范围（写入操作）">
如果你希望传出消息使用当前智能体身份（自定义用户名和图标），而不是默认的 Slack 应用身份，请添加 `chat:write.customize` bot 范围。
如果你使用 emoji 图标，Slack 期望使用 `:emoji_name:` 语法。
如果你使用 emoji 图标，Slack 需要 `:emoji_name:` 语法。
</Accordion>
<Accordion title="Optional user-token scopes (read operations)">
如果你配置了 `channels.slack.userToken`，典型读取 scope 包括：
<Accordion title="可选用户令牌范围（读取操作）">
如果你配置了 `channels.slack.userToken`，典型读取范围为：
- `channels:history`, `groups:history`, `im:history`, `mpim:history`
- `channels:read`, `groups:read`, `im:read`, `mpim:read`
@ -447,41 +447,41 @@ OpenClaw 默认将 Socket Mode 的 Slack SDK 客户端 pong 超时设置为 15
- Socket Mode 需要 `botToken` + `appToken`。
- HTTP 模式需要 `botToken` + `signingSecret`。
- `botToken`、`appToken`、`signingSecret` 和 `userToken` 接受明文字符串或 SecretRef 对象。
- 配置令牌会覆盖环境变量回退值。
- 配置令牌会覆盖环境变量回退。
- `SLACK_BOT_TOKEN` / `SLACK_APP_TOKEN` 环境变量回退仅适用于默认账号。
- `userToken` (`xoxp-...`) 仅可通过配置设置（无环境变量回退），并且默认使用只读行为 (`userTokenReadOnly: true`)。
- `userToken`（`xoxp-...`）仅可通过配置设置（无环境变量回退），并且默认为只读行为（`userTokenReadOnly: true`）。
Status 快照行为：
- Slack 账号检查会按凭证跟踪 `*Source` 和 `*Status` 字段（`botToken`、`appToken`、`signingSecret`、`userToken`）。
- Slack 账号检查会按凭据跟踪 `*Source` 和 `*Status` 字段（`botToken`、`appToken`、`signingSecret`、`userToken`）。
- Status 为 `available`、`configured_unavailable` 或 `missing`。
- `configured_unavailable` 表示账号通过 SecretRef 或其他非内联密钥来源配置，但当前命令/运行时路径无法解析实际值。
- 在 HTTP 模式下，会包含 `signingSecretStatus`；在 Socket Mode 下，必需组合是 `botTokenStatus` + `appTokenStatus`。
- `configured_unavailable` 表示该账号通过 SecretRef 或其他非内联密钥源进行了配置，但当前命令/运行时路径无法解析实际值。
- 在 HTTP 模式下，会包含 `signingSecretStatus`；在 Socket Mode 下，所需配对是 `botTokenStatus` + `appTokenStatus`。
<Tip>
对于动作/目录读取，配置后可优先使用用户令牌。对于写入，仍优先使用机器人令牌；仅当 `userTokenReadOnly: false` 且机器人令牌不可用时，才允许用户令牌写入。
对于操作/目录读取，配置后可以优先使用用户令牌。对于写入，仍优先使用机器人令牌；只有当 `userTokenReadOnly: false` 且机器人令牌不可用时，才允许用户令牌写入。
</Tip>
## 动作和门控
## 操作和门控
Slack 动作由 `channels.slack.actions.*` 控制。
Slack 操作由 `channels.slack.actions.*` 控制。
当前 Slack 工具中可用的动作组：
当前 Slack 工具中可用的操作分组：
| 组 | 默认值 |
| ---------- | ------ |
| 分组 | 默认值 |
| ---------- | ------- |
| messages | 已启用 |
| reactions | 已启用 |
| pins | 已启用 |
| memberInfo | 已启用 |
| emojiList | 已启用 |
当前 Slack 消息动作包括 `send`、`upload-file`、`download-file`、`read`、`edit`、`delete`、`pin`、`unpin`、`list-pins`、`member-info` 和 `emoji-list`。`download-file` 接受入站文件占位符中显示的 Slack 文件 ID，并为图像返回图像预览，或为其他文件类型返回本地文件元数据。
当前 Slack 消息操作包括 `send`、`upload-file`、`download-file`、`read`、`edit`、`delete`、`pin`、`unpin`、`list-pins`、`member-info` 和 `emoji-list`。`download-file` 接受入站文件占位符中显示的 Slack 文件 ID，并为图片返回图片预览，或为其他文件类型返回本地文件元数据。
## 访问控制和路由
<Tabs>
<Tab title="DM policy">
<Tab title="私信策略">
`channels.slack.dmPolicy` 控制私信访问。`channels.slack.allowFrom` 是规范的私信允许列表。
- `pairing`（默认）
@ -500,7 +500,7 @@ Slack 动作由 `channels.slack.actions.*` 控制。
多账号优先级：
- `channels.slack.accounts.default.allowFrom` 仅适用于 `default` 账号。
- 命名账号在自身未设置 `allowFrom` 时继承 `channels.slack.allowFrom`。
- 命名账号在自己的 `allowFrom` 未设置时继承 `channels.slack.allowFrom`。
- 命名账号不会继承 `channels.slack.accounts.default.allowFrom`。
旧版 `channels.slack.dm.policy` 和 `channels.slack.dm.allowFrom` 仍会读取以保持兼容。`openclaw doctor --fix` 会在不改变访问权限的情况下，将它们迁移到 `dmPolicy` 和 `allowFrom`。
@ -509,7 +509,7 @@ Slack 动作由 `channels.slack.actions.*` 控制。
</Tab>
<Tab title="Channel policy">
<Tab title="渠道策略">
`channels.slack.groupPolicy` 控制渠道处理：
- `open`
@ -522,14 +522,14 @@ Slack 动作由 `channels.slack.actions.*` 控制。
名称/ID 解析：
- 渠道允许列表条目和私信允许列表条目会在启动时解析，前提是令牌访问允许
- 未解析的渠道名称条目会按配置保留，但默认会被路由忽略
- 当令牌访问允许时，渠道允许列表条目和私信允许列表条目会在启动时解析
- 未解析的渠道名称条目会按配置保留，但默认会在路由中忽略
- 入站授权和渠道路由默认优先使用 ID；直接用户名/slug 匹配需要 `channels.slack.dangerouslyAllowNameMatching: true`
<Warning>
基于名称的键（`#channel-name` 或 `channel-name`）在 `groupPolicy: "allowlist"` 下**不会**匹配。渠道查找默认优先使用 ID，因此基于名称的键永远无法成功路由，该渠道中的所有消息都会被静默阻止。这不同于 `groupPolicy: "open"`，后者不要求渠道键参与路由，因此基于名称的键看起来可以工作。
基于名称的键（`#channel-name` 或 `channel-name`）在 `groupPolicy: "allowlist"` 下**不会**匹配。渠道查找默认优先使用 ID，因此基于名称的键永远无法成功路由，该渠道中的所有消息都会被静默阻止。这不同于 `groupPolicy: "open"`，后者不要求渠道键用于路由，基于名称的键看起来可以工作。
始终使用 Slack 渠道 ID 作为键。查找方法：在 Slack 中右键点击渠道 → **复制链接** — ID（`C...`）会出现在 URL 末尾。
始终使用 Slack 渠道 ID 作为键。查找方式：在 Slack 中右键点击渠道 → **Copy link** — ID（`C...`）会出现在 URL 末尾。
正确：
@ -564,16 +564,16 @@ Slack 动作由 `channels.slack.actions.*` 控制。
</Tab>
<Tab title="Mentions and channel users">
渠道消息默认受提及门控控制。
<Tab title="提及和渠道用户">
渠道消息默认由提及门控。
提及来源：
- 显式应用提及（`<@botId>`）
- 提及正则模式（`agents.list[].groupChat.mentionPatterns`，回退到 `messages.groupChat.mentionPatterns`）
- 提及正则模式（`agents.list[].groupChat.mentionPatterns`，回退为 `messages.groupChat.mentionPatterns`）
- 隐式回复机器人线程行为（当 `thread.requireExplicitMention` 为 `true` 时禁用）
单渠道控制（`channels.slack.channels.<id>`；名称仅通过启动解析或 `dangerouslyAllowNameMatching` 可用）：
按渠道控制（`channels.slack.channels.<id>`；名称仅可通过启动解析或 `dangerouslyAllowNameMatching` 使用）：
- `requireMention`
- `users`（允许列表）
@ -584,6 +584,8 @@ Slack 动作由 `channels.slack.actions.*` 控制。
- `toolsBySender` 键格式：`id:`、`e164:`、`username:`、`name:` 或 `"*"` 通配符
（旧版无前缀键仍仅映射到 `id:`）
`allowBots` 对渠道和私有渠道较为保守：只有当发送机器人被明确列入该房间的 `users` 允许列表，或者 `channels.slack.allowFrom` 中至少一个显式 Slack 所有者 ID 当前是房间成员时，才会接受机器人发出的房间消息。通配符和显示名称所有者条目不满足所有者在场要求。所有者在场使用 Slack `conversations.members`；请确保应用拥有与房间类型匹配的读取范围（公共渠道为 `channels:read`，私有渠道为 `groups:read`）。如果成员查找失败，OpenClaw 会丢弃机器人发出的房间消息。
</Tab>
</Tabs>
@ -592,10 +594,10 @@ Slack 动作由 `channels.slack.actions.*` 控制。
- 私信路由为 `direct`；渠道路由为 `channel`；MPIM 路由为 `group`。
- 使用默认 `session.dmScope=main` 时，Slack 私信会折叠到智能体主会话。
- 渠道会话：`agent:<agentId>:slack:channel:<channelId>`。
- 线程回复在适用时可创建线程会话后缀（`:thread:<threadTs>`）。
- 线程回复可在适用时创建线程会话后缀（`:thread:<threadTs>`）。
- `channels.slack.thread.historyScope` 默认值为 `thread`；`thread.inheritParent` 默认值为 `false`。
- `channels.slack.thread.initialHistoryLimit` 控制新线程会话启动时获取多少条现有线程消息（默认 `20`；设置为 `0` 可禁用）。
- `channels.slack.thread.requireExplicitMention`（默认 `false`）：当为 `true` 时，抑制隐式线程提及，因此机器人仅响应线程中显式的 `@bot` 提及，即使机器人已经参与过该线程。若不设置此项，机器人参与过的线程中的回复会绕过 `requireMention` 门控。
- `channels.slack.thread.initialHistoryLimit` 控制新线程会话启动时获取多少条现有线程消息（默认 `20`；设为 `0` 可禁用）。
- `channels.slack.thread.requireExplicitMention`（默认 `false`）：当为 `true` 时，会抑制隐式线程提及，使机器人只响应线程内显式 `@bot` 提及，即使机器人已经参与了该线程。没有此设置时，机器人参与过的线程中的回复会绕过 `requireMention` 门控。
回复线程控制：
@ -609,19 +611,19 @@ Slack 动作由 `channels.slack.actions.*` 控制。
- `[[reply_to:<id>]]`
<Note>
`replyToMode="off"` 会禁用 Slack 中的**所有**回复线程，包括显式 `[[reply_to_*]]` 标签。这不同于 Telegram，后者在 `"off"` 模式下仍会遵循显式标签。Slack 线程会从渠道中隐藏消息，而 Telegram 回复仍以内联方式可见。
`replyToMode="off"` 会在 Slack 中禁用**所有**回复线程，包括显式 `[[reply_to_*]]` 标签。这不同于 Telegram，在 Telegram 中，显式标签在 `"off"` 模式下仍会被遵循。Slack 线程会将消息隐藏在渠道之外，而 Telegram 回复会保持内联可见。
</Note>
## 确认反应
`ackReaction` 会在 OpenClaw 处理入站消息时发送一个确认 emoji。
`ackReaction` 会在 OpenClaw 处理入站消息时发送确认表情符号。
解析顺序：
- `channels.slack.accounts.<accountId>.ackReaction`
- `channels.slack.ackReaction`
- `messages.ackReaction`
- 智能体身份 emoji 回退（`agents.list[].identity.emoji`，否则为 "👀"）
- 智能体身份表情符号回退（`agents.list[].identity.emoji`，否则为 "👀"）
注意事项：
@ -635,16 +637,16 @@ Slack 动作由 `channels.slack.actions.*` 控制。
- `off`：禁用实时预览流式传输。
- `partial`（默认）：用最新的部分输出替换预览文本。
- `block`：追加分块预览更新。
- `progress`：生成期间显示进度状态文本，然后发送最终文本。
- `streaming.preview.toolProgress`：当草稿预览处于活动状态时，将工具/进度更新路由到同一条编辑后的预览消息中（默认：`true`）。设置为 `false` 可保留单独的工具/进度消息。
- `progress`：生成时显示进度状态文本，然后发送最终文本。
- `streaming.preview.toolProgress`：当草稿预览处于活动状态时，将工具/进度更新路由到同一条编辑后的预览消息中（默认：`true`）。设为 `false` 可保留单独的工具/进度消息。
当 `channels.slack.streaming.mode` 为 `partial` 时，`channels.slack.streaming.nativeTransport` 控制 Slack 原生文本流式传输（默认：`true`）。
- 必须有可用的回复线程，才会显示原生文本流式传输和 Slack assistant 线程 Status。线程选择仍遵循 `replyToMode`。
- 当原生流式传输不可用时，渠道和群组聊天根消息仍可使用普通草稿预览。
- 顶层 Slack 私信默认不在线程中，因此不会显示线程样式预览；如果你希望在那里显示可见进度，请使用线程回复或 `typingReaction`。
- 必须有可用的回复线程，原生文本流式传输和 Slack 助手线程 Status 才会显示。线程选择仍遵循 `replyToMode`。
- 当原生流式传输不可用时，渠道和群聊根消息仍可使用普通草稿预览。
- 顶层 Slack 私信默认保持在线程外，因此不会显示线程样式预览；如果想在那里看到可见进度，请使用线程回复或 `typingReaction`。
- 媒体和非文本载荷会回退到普通投递。
- 媒体/错误最终消息会取消待处理的预览编辑；符合条件的文本/分块最终消息仅在可以就地编辑预览时刷新。
- 媒体/错误最终消息会取消待处理的预览编辑；符合条件的文本/分块最终消息仅在能就地编辑预览时刷新。
- 如果流式传输在回复中途失败，OpenClaw 会对剩余载荷回退到普通投递。
使用草稿预览而不是 Slack 原生文本流式传输：
@ -668,9 +670,9 @@ Slack 动作由 `channels.slack.actions.*` 控制。
- 布尔值 `channels.slack.streaming` 会自动迁移到 `channels.slack.streaming.mode` 和 `channels.slack.streaming.nativeTransport`。
- 旧版 `channels.slack.nativeStreaming` 会自动迁移到 `channels.slack.streaming.nativeTransport`。
## 输入反应回退
## 输入中反应回退
`typingReaction` 会在 OpenClaw 处理回复时，为入站 Slack 消息添加一个临时反应，并在运行结束时移除它。这在线程回复之外最有用，因为线程回复会使用默认的“is typing...”状态指示器。
`typingReaction` 会在 OpenClaw 处理回复时向入站 Slack 消息添加临时反应，并在运行结束时移除。它在线程回复之外最有用，因为线程回复会使用默认的 "is typing..." 状态指示器。
解析顺序：
@ -680,29 +682,29 @@ Slack 动作由 `channels.slack.actions.*` 控制。
注意事项：
- Slack 需要短代码（例如 `"hourglass_flowing_sand"`）。
- 该反应会尽力执行，并会在回复或失败路径完成后自动尝试清理。
- 该反应尽力执行，并且会在回复或失败路径完成后自动尝试清理。
## 媒体、分块和投递
<AccordionGroup>
<Accordion title="Inbound attachments">
<Accordion title="入站附件">
Slack 文件附件会从 Slack 托管的私有 URL 下载（令牌认证请求流程），并在获取成功且大小限制允许时写入媒体存储。文件占位符包含 Slack `fileId`，因此智能体可以使用 `download-file` 获取原始文件。
下载使用有界空闲超时和总超时。如果 Slack 文件检索停滞或失败，OpenClaw 会继续处理消息，并回退到文件占位符。
下载使用有界的空闲和总超时。如果 Slack 文件检索停滞或失败，OpenClaw 会继续处理消息，并回退到文件占位符。
运行时入站大小上限默认是 `20MB`，除非被 `channels.slack.mediaMaxMb` 覆盖。
运行时入站大小上限默认为 `20MB`，除非由 `channels.slack.mediaMaxMb` 覆盖。
</Accordion>
<Accordion title="Outbound text and files">
- 文本分块使用 `channels.slack.textChunkLimit`（默认 4000）
<Accordion title="出站文本和文件">
- 文本块使用 `channels.slack.textChunkLimit`（默认 4000）
- `channels.slack.chunkMode="newline"` 启用段落优先拆分
- 文件发送使用 Slack 上传 API，并且可以包含线程回复（`thread_ts`）
- 配置后，出站媒体上限遵循 `channels.slack.mediaMaxMb`；否则渠道发送使用媒体管线中的 MIME 类型默认值
- 配置后，出站媒体上限遵循 `channels.slack.mediaMaxMb`；否则，渠道发送使用媒体管线中的 MIME 类型默认值
</Accordion>
<Accordion title="Delivery targets">
<Accordion title="投递目标">
首选显式目标：
- `user:<id>` 用于私信
@ -715,7 +717,7 @@ Slack 动作由 `channels.slack.actions.*` 控制。
## 命令和斜杠行为
斜杠命令在 Slack 中表现为单个已配置命令或多个原生命令。配置 `channels.slack.slashCommand` 可更改命令默认值：
斜杠命令在 Slack 中会显示为一个已配置命令或多个原生命令。配置 `channels.slack.slashCommand` 可更改命令默认值：
- `enabled: false`
- `name: "openclaw"`
@ -726,19 +728,19 @@ Slack 动作由 `channels.slack.actions.*` 控制。
/openclaw /help
```
原生命令要求你的 Slack 应用中有[额外的清单设置](#additional-manifest-settings)，并且改为通过全局配置中的 `channels.slack.commands.native: true` 或 `commands.native: true` 启用。
原生命令需要在你的 Slack 应用中配置[额外 manifest 设置](#additional-manifest-settings)，并改用 `channels.slack.commands.native: true` 启用，或在全局配置中使用 `commands.native: true` 启用。
- Slack 的原生命令自动模式默认**关闭**，因此 `commands.native: "auto"` 不会启用 Slack 原生命令。
- Slack 的原生命令自动模式为**关闭**，因此 `commands.native: "auto"` 不会启用 Slack 原生命令。
```txt
/help
```
原生参数菜单使用自适应渲染策略，会在分发所选选项值之前显示确认模态框：
原生参数菜单使用自适应渲染策略，在派发所选选项值之前显示确认模态框：
- 最多 5 个选项：按钮块
- 6-100 个选项：静态选择菜单
- 超过 100 个选项：当交互选项处理程序可用时，使用带异步选项过滤的外部选择
- 超过 100 个选项：在交互选项处理器可用时使用带异步选项过滤的外部选择
- 超出 Slack 限制：编码后的选项值回退为按钮
```txt
@ -749,7 +751,7 @@ Slack 动作由 `channels.slack.actions.*` 控制。
## 交互式回复
Slack 可以渲染智能体创作的交互式回复控件，但此功能默认禁用。
Slack 可以渲染智能体编写的交互式回复控件，但此功能默认禁用。
全局启用：
@ -788,37 +790,36 @@ Slack 可以渲染智能体创作的交互式回复控件，但此功能默认
- `[[slack_buttons: Approve:approve, Reject:reject]]`
- `[[slack_select: Choose a target | Canary:canary, Production:production]]`
这些指令会编译成 Slack Block Kit，并通过现有的 Slack 交互事件路径路由点击或选择。
这些指令会编译为 Slack Block Kit，并通过现有 Slack 交互事件路径把点击或选择路由回来。
注意：
- 这是 Slack 专用 UI。其他渠道不会把 Slack Block Kit 指令转换成自己的按钮系统。
- 交互式回调值是 OpenClaw 生成的不透明令牌，而不是智能体创作的原始值。
- 如果生成的交互式块会超出 Slack Block Kit 限制，OpenClaw 会回退为原始文本回复，而不是发送无效的块载荷。
- 这是 Slack 专用 UI。其他渠道不会把 Slack Block Kit 指令翻译成自己的按钮系统。
- 交互式回调值是 OpenClaw 生成的不透明令牌，不是智能体编写的原始值。
- 如果生成的交互块会超出 Slack Block Kit 限制，OpenClaw 会回退到原始文本回复，而不是发送无效的 blocks payload。
## Slack 中的 Exec 审批
Slack 可以作为带交互式按钮和交互的原生审批客户端，而不是回退到 Web UI 或终端。
Slack 可以作为带有交互式按钮和交互的原生审批客户端，而不是回退到 Web UI 或终端。
- Exec 审批使用 `channels.slack.execApprovals.*` 进行原生私信/渠道路由。
- 当请求已经落在 Slack 中，并且审批 ID 类型是 `plugin:` 时，插件审批仍可通过同一个 Slack 原生按钮界面完成。
- 当请求已经落在 Slack 中且审批 ID kind 为 `plugin:` 时，插件审批仍可通过同一个 Slack 原生按钮界面完成。
- 审批人授权仍会强制执行：只有被识别为审批人的用户才能通过 Slack 批准或拒绝请求。
这使用与其他渠道相同的共享审批按钮界面。当你的 Slack 应用设置中启用 `interactivity` 时，审批提示会直接在对话中渲染为 Block Kit 按钮。
当这些按钮存在时，它们就是主要审批 UX；只有当工具结果表示聊天
审批不可用，或手动审批是唯一路径时，OpenClaw
这使用与其他渠道相同的共享审批按钮界面。当你的 Slack 应用设置中启用了 `interactivity` 时，审批提示会直接在对话中渲染为 Block Kit 按钮。
当这些按钮存在时，它们就是主要审批 UX；OpenClaw
只有在工具结果显示聊天审批不可用，或手动审批是唯一路径时，
才应包含手动 `/approve` 命令。
配置路径：
- `channels.slack.execApprovals.enabled`
- `channels.slack.execApprovals.approvers`（可选；可能时回退到 `commands.ownerAllowFrom`）
- `channels.slack.execApprovals.approvers`（可选；可行时回退到 `commands.ownerAllowFrom`）
- `channels.slack.execApprovals.target`（`dm` | `channel` | `both`，默认：`dm`）
- `agentFilter`、`sessionFilter`
- `agentFilter`, `sessionFilter`
当 `enabled` 未设置或为 `"auto"` 且至少能解析出一个
审批人时，Slack 会自动启用原生 exec 审批。设置 `enabled: false` 可明确禁用 Slack 作为原生审批客户端。
设置 `enabled: true` 可在审批人解析成功时强制启用原生审批。
当 `enabled` 未设置或为 `"auto"` 且至少解析出一个审批人时，Slack 会自动启用原生 exec 审批。设置 `enabled: false` 可显式禁用 Slack 作为原生审批客户端。
当审批人可解析时，设置 `enabled: true` 可强制启用原生审批。
没有显式 Slack exec 审批配置时的默认行为：
@ -830,8 +831,7 @@ Slack 可以作为带交互式按钮和交互的原生审批客户端，而不
}
```
只有在你想覆盖审批人、添加过滤器或
选择源聊天递送时，才需要显式 Slack 原生配置：
仅当你想覆盖审批人、添加过滤器，或选择加入原始聊天投递时，才需要显式 Slack 原生配置：
```json5
{
@ -847,24 +847,22 @@ Slack 可以作为带交互式按钮和交互的原生审批客户端，而不
}
```
共享 `approvals.exec` 转发是独立的。只有当 exec 审批提示还必须
路由到其他聊天或显式带外目标时才使用它。共享 `approvals.plugin` 转发也是
独立的；当这些请求已经落在 Slack 中时，Slack 原生按钮仍可完成插件审批。
共享 `approvals.exec` 转发是独立的。仅当 exec 审批提示还必须路由到其他聊天或显式带外目标时才使用它。共享 `approvals.plugin` 转发也是独立的；当这些请求已经落在 Slack 中时，Slack 原生按钮仍可完成插件审批。
同聊天 `/approve` 也可在已经支持命令的 Slack 渠道和私信中使用。参见 [Exec 审批](/zh-CN/tools/exec-approvals)，了解完整的审批转发模型。
同一聊天中的 `/approve` 也适用于已经支持命令的 Slack 渠道和私信。完整审批转发模型见 [Exec 审批](/zh-CN/tools/exec-approvals)。
## 事件和运行行为
## 事件和运维行为
- 消息编辑/删除会映射为系统事件。
- 线程广播（“同时发送到渠道”的线程回复）会作为普通用户消息处理。
- 线程广播（“也发送到渠道”的线程回复）会按普通用户消息处理。
- 表情反应添加/移除事件会映射为系统事件。
- 成员加入/离开、渠道创建/重命名，以及置顶添加/移除事件会映射为系统事件。
- 成员加入/离开、渠道创建/重命名，以及 pin 添加/移除事件会映射为系统事件。
- 启用 `configWrites` 时，`channel_id_changed` 可以迁移渠道配置键。
- 渠道主题/用途元数据会被视为不可信上下文，并且可以注入到路由上下文中。
- 适用时，线程发起者和初始线程历史上下文种子会按配置的发送者允许列表过滤。
- 块操作和模态框交互会发出带有丰富载荷字段的结构化 `Slack interaction: ...` 系统事件：
- 块操作：所选值、标签、选择器值以及 `workflow_*` 元数据
- 模态框 `view_submission` 和 `view_closed` 事件，包含已路由的渠道元数据和表单输入
- 适用时，线程起始消息和初始线程历史上下文播种会按已配置的发送者 allowlist 过滤。
- Block actions 和模态框交互会发出带有丰富 payload 字段的结构化 `Slack interaction: ...` 系统事件：
- block actions：所选值、标签、选择器值，以及 `workflow_*` 元数据
- 模态框 `view_submission` 和 `view_closed` 事件，包含路由后的渠道元数据和表单输入
## 配置参考
@ -872,13 +870,13 @@ Slack 可以作为带交互式按钮和交互的原生审批客户端，而不
<Accordion title="高信号 Slack 字段">
- 模式/认证：`mode`、`botToken`、`appToken`、`signingSecret`、`webhookPath`、`accounts.*`
- 私信访问：`dm.enabled`、`dmPolicy`、`allowFrom`（旧版：`dm.policy`、`dm.allowFrom`）、`dm.groupEnabled`、`dm.groupChannels`
- 兼容性开关：`dangerouslyAllowNameMatching`（破窗选项；除非需要，否则保持关闭）
- 渠道访问：`groupPolicy`、`channels.*`、`channels.*.users`、`channels.*.requireMention`
- 线程/历史：`replyToMode`、`replyToModeByChatType`、`thread.*`、`historyLimit`、`dmHistoryLimit`、`dms.*.historyLimit`
- 递送：`textChunkLimit`、`chunkMode`、`mediaMaxMb`、`streaming`、`streaming.nativeTransport`、`streaming.preview.toolProgress`
- 运维/功能：`configWrites`、`commands.native`、`slashCommand.*`、`actions.*`、`userToken`、`userTokenReadOnly`
- 模式/凭证：`mode`, `botToken`, `appToken`, `signingSecret`, `webhookPath`, `accounts.*`
- 私信访问：`dm.enabled`, `dmPolicy`, `allowFrom`（旧版：`dm.policy`, `dm.allowFrom`）, `dm.groupEnabled`, `dm.groupChannels`
- 兼容性开关：`dangerouslyAllowNameMatching`（紧急开关；除非需要，否则保持关闭）
- 渠道访问：`groupPolicy`, `channels.*`, `channels.*.users`, `channels.*.requireMention`
- 线程/历史：`replyToMode`, `replyToModeByChatType`, `thread.*`, `historyLimit`, `dmHistoryLimit`, `dms.*.historyLimit`
- 投递：`textChunkLimit`, `chunkMode`, `mediaMaxMb`, `streaming`, `streaming.nativeTransport`, `streaming.preview.toolProgress`
- 运维/功能：`configWrites`, `commands.native`, `slashCommand.*`, `actions.*`, `userToken`, `userTokenReadOnly`
</Accordion>
@ -889,11 +887,11 @@ Slack 可以作为带交互式按钮和交互的原生审批客户端，而不
按顺序检查：
- `groupPolicy`
- 渠道允许列表（`channels.slack.channels`）— **键必须是渠道 ID**（`C12345678`），不能是名称（`#channel-name`）。在 `groupPolicy: "allowlist"` 下，基于名称的键会静默失败，因为渠道路由默认优先使用 ID。查找 ID：在 Slack 中右键点击渠道 → **复制链接** — URL 末尾的 `C...` 值就是渠道 ID。
- 渠道 allowlist（`channels.slack.channels`）——**键必须是渠道 ID**（`C12345678`），不是名称（`#channel-name`）。在 `groupPolicy: "allowlist"` 下，基于名称的键会静默失败，因为渠道路由默认以 ID 优先。查找 ID：在 Slack 中右键点击渠道 → **复制链接** —— URL 末尾的 `C...` 值就是渠道 ID。
- `requireMention`
- 按渠道配置的 `users` 允许列表
- 按渠道配置的 `users` allowlist
有用命令：
有用的命令：
```bash
openclaw channels status --probe
@ -908,10 +906,10 @@ openclaw doctor
- `channels.slack.dm.enabled`
- `channels.slack.dmPolicy`（或旧版 `channels.slack.dm.policy`）
- 配对审批 / 允许列表条目
- 配对审批 / allowlist 条目
- Slack Assistant 私信事件：提到 `drop message_changed` 的详细日志
通常意味着 Slack 发送了已编辑的 Assistant 线程事件，而消息元数据中
没有可恢复的人类发送者
通常意味着 Slack 发送了一个已编辑的 Assistant 线程事件，
且消息元数据中没有可恢复的人类发送者
```bash
openclaw pairing list slack
@ -919,125 +917,124 @@ openclaw pairing list slack
</Accordion>
<Accordion title="Socket 模式未连接">
验证 Slack 应用设置中的 bot + app 令牌以及 Socket Mode 启用状态。
<Accordion title="Socket mode 未连接">
验证 Slack 应用设置中的 bot + app token 和 Socket Mode 启用状态。
如果 `openclaw channels status --probe --json` 显示 `botTokenStatus` 或
`appTokenStatus: "configured_unavailable"`，则 Slack 账号已配置，
但当前运行时无法解析由 SecretRef 支持的
值。
`appTokenStatus: "configured_unavailable"`，则表示 Slack 账号已配置，
但当前运行时无法解析 SecretRef 支持的值。
</Accordion>
<Accordion title="HTTP 模式未接收事件">
<Accordion title="HTTP mode 未接收事件">
验证：
- 签名密钥
- webhook 路径
- Slack 请求 URL（事件 + 交互性 + 斜杠命令）
- 每个 HTTP 账号唯一的 `webhookPath`
- signing secret
- webhook path
- Slack Request URL（Events + Interactivity + Slash Commands）
- 每个 HTTP 账号使用唯一的 `webhookPath`
如果账号快照中出现 `signingSecretStatus: "configured_unavailable"`，
则 HTTP 账号已配置，但当前运行时无法
解析由 SecretRef 支持的签名密钥。
则表示 HTTP 账号已配置，但当前运行时无法解析 SecretRef 支持的
signing secret。
</Accordion>
<Accordion title="原生命令/斜杠命令未触发">
验证你原本打算使用的是：
<Accordion title="原生/斜杠命令未触发">
确认你的预期是：
- 原生命令模式（`channels.slack.commands.native: true`），并且在 Slack 中注册了匹配的斜杠命令
- 或单一斜杠命令模式（`channels.slack.slashCommand.enabled: true`）
同时检查 `commands.useAccessGroups` 和渠道/用户允许列表。
同时检查 `commands.useAccessGroups` 以及渠道/用户 allowlist。
</Accordion>
</AccordionGroup>
## 附件视觉参考
当 Slack 文件下载成功且大小限制允许时，Slack 可以把下载的媒体附加到智能体回合。图片文件可以通过媒体理解路径传递，或直接传递给具备视觉能力的回复模型；其他文件会作为可下载文件上下文保留，而不是作为图片输入处理。
当 Slack 文件下载成功且大小限制允许时，Slack 可以把下载的媒体附加到智能体 turn。图像文件可以通过媒体理解路径传递，也可以直接传给支持视觉的回复模型；其他文件会保留为可下载文件上下文，而不是作为图像输入处理。
### 支持的媒体类型
| 媒体类型 | 来源 | 当前行为 | 备注 |
| 媒体类型 | 来源 | 当前行为 | 注意事项 |
| ------------------------------ | -------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| JPEG / PNG / GIF / WebP 图片 | Slack 文件 URL | 下载并附加到回合，用于具备视觉能力的处理 | 单文件上限：`channels.slack.mediaMaxMb`（默认 20 MB） |
| PDF 文件 | Slack 文件 URL | 下载并作为文件上下文暴露给 `download-file` 或 `pdf` 等工具 | Slack 入站不会自动把 PDF 转换为图片视觉输入 |
| 其他文件 | Slack 文件 URL | 尽可能下载并作为文件上下文暴露 | 二进制文件不会作为图片输入处理 |
| 线程回复 | 线程发起消息文件 | 当回复本身没有直接媒体时，根消息文件可以作为上下文补充加载 | 仅文件的发起消息使用附件占位符 |
| 多图片消息 | 多个 Slack 文件 | 每个文件都会独立评估 | Slack 处理限制为每条消息最多八个文件 |
| JPEG / PNG / GIF / WebP 图像 | Slack 文件 URL | 下载并附加到 turn 以进行支持视觉的处理 | 单文件上限：`channels.slack.mediaMaxMb`（默认 20 MB） |
| PDF 文件 | Slack 文件 URL | 下载并暴露为文件上下文，供 `download-file` 或 `pdf` 等工具使用 | Slack 入站不会自动把 PDF 转换为图像视觉输入 |
| 其他文件 | Slack 文件 URL | 可行时下载并暴露为文件上下文 | 二进制文件不会作为图像输入处理 |
| 线程回复 | 线程起始消息文件 | 当回复没有直接媒体时，根消息文件可以作为上下文补全 | 仅文件的起始消息使用附件占位符 |
| 多图像消息 | 多个 Slack 文件 | 每个文件独立评估 | Slack 处理每条消息最多限制为八个文件 |
### 入站流水线
### 入站管线
当带文件附件的 Slack 消息到达时：
当带有文件附件的 Slack 消息到达时：
1. OpenClaw 使用 bot 令牌（`xoxb-...`）从 Slack 的私有 URL 下载文件。
2. 下载成功后，文件会写入媒体存储。
1. OpenClaw 使用机器人令牌（`xoxb-...`）从 Slack 的私有 URL 下载文件。
2. 文件在成功后写入媒体存储。
3. 下载的媒体路径和内容类型会添加到入站上下文。
4. 支持图片的模型/工具路径可以使用该上下文中的图片附件。
5. 非图片文件仍可作为文件元数据或媒体引用提供给能处理它们的工具。
4. 支持图像的模型/工具路径可以使用该上下文中的图像附件。
5. 非图像文件仍可作为文件元数据或媒体引用提供给能够处理它们的工具。
### 线程根附件继承
当消息在线程中到达（有一个 `thread_ts` 父级）时：
当消息到达线程中（有一个 `thread_ts` 父级）时：
- 如果回复本身没有直接媒体，而包含的根消息有文件，Slack 可以将根文件作为线程发起者上下文补充加载。
- 如果回复本身没有直接媒体，而包含的根消息有文件，Slack 可以将根文件水合为线程起始上下文。
- 直接回复附件优先于根消息附件。
- 只有文件且没有文本的根消息会用附件占位符表示，因此回退仍可包含其文件。
- 只有文件而没有文本的根消息会用附件占位符表示，因此回退仍可包含其文件。
### 多附件处理
当单条 Slack 消息包含多个文件附件时：
当一条 Slack 消息包含多个文件附件时：
- 每个附件都会通过媒体流水线独立处理。
- 下载的媒体引用会汇总到消息上下文中。
- 处理顺序遵循事件负载中 Slack 的文件顺序。
- 下载的媒体引用会聚合到消息上下文中。
- 处理顺序遵循事件载荷中的 Slack 文件顺序。
- 一个附件下载失败不会阻塞其他附件。
### 大小、下载与模型限制
### 大小、下载和模型限制
- **大小上限**：默认每个文件 20 MB。可通过 `channels.slack.mediaMaxMb` 配置。
- **下载失败**：Slack 无法提供的文件、过期 URL、无法访问的文件、超大文件，以及 Slack 凭证/登录 HTML 响应都会被跳过，而不会被报告为不支持的格式。
- **视觉模型**：图像分析会在主动回复模型支持视觉能力时使用该模型，否则使用在 `agents.defaults.imageModel` 配置的图像模型。
- **下载失败**：Slack 无法提供的文件、过期 URL、不可访问的文件、超大文件以及 Slack 认证/登录 HTML 响应会被跳过，而不是报告为不支持的格式。
- **视觉模型**：当活跃回复模型支持视觉时，图像分析使用该模型；否则使用在 `agents.defaults.imageModel` 配置的图像模型。
### 已知限制
| 场景 | 当前行为 | 解决方法 |
| 场景 | 当前行为 | 解决方法 |
| -------------------------------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| 过期的 Slack 文件 URL | 跳过文件；不显示错误 | 在 Slack 中重新上传文件 |
| 未配置视觉模型 | 图像附件会存储为媒体引用，但不会作为图像分析 | 配置 `agents.defaults.imageModel`，或使用具备视觉能力的回复模型 |
| 非常大的图像（默认 > 20 MB） | 按大小上限跳过 | 如果 Slack 允许，请增大 `channels.slack.mediaMaxMb` |
| 转发/共享的附件 | 文本和 Slack 托管的图像/文件媒体会尽力处理 | 直接在 OpenClaw 线程中重新共享 |
| PDF 附件 | 存储为文件/媒体上下文，不会自动通过图像视觉处理 | 使用 `download-file` 获取文件元数据，或使用 `pdf` 工具进行 PDF 分析 |
| 过期的 Slack 文件 URL | 文件被跳过；不显示错误 | 在 Slack 中重新上传文件 |
| 未配置视觉模型 | 图像附件会作为媒体引用存储，但不会作为图像分析 | 配置 `agents.defaults.imageModel`，或使用支持视觉的回复模型 |
| 非常大的图像（默认 > 20 MB） | 按大小上限跳过 | 如果 Slack 允许，增大 `channels.slack.mediaMaxMb` |
| 转发/共享附件 | 文本和 Slack 托管的图像/文件媒体会尽力处理 | 直接在 OpenClaw 线程中重新共享 |
| PDF 附件 | 作为文件/媒体上下文存储，不会自动通过图像视觉路由 | 使用 `download-file` 获取文件元数据，或使用 `pdf` 工具进行 PDF 分析 |
### 相关文档
- [媒体理解流水线](/zh-CN/nodes/media-understanding)
- [PDF 工具](/zh-CN/tools/pdf)
- Epic: [#51349](https://github.com/openclaw/openclaw/issues/51349) — Slack 附件视觉启用
- 回归测试：[#51353](https://github.com/openclaw/openclaw/issues/51353)
- 实时验证：[#51354](https://github.com/openclaw/openclaw/issues/51354)
- 回归测试: [#51353](https://github.com/openclaw/openclaw/issues/51353)
- 实时验证: [#51354](https://github.com/openclaw/openclaw/issues/51354)
## 相关
<CardGroup cols={2}>
<Card title="Pairing" icon="link" href="/zh-CN/channels/pairing">
将 Slack 用户与 Gateway 网关配对。
<Card title="配对" icon="link" href="/zh-CN/channels/pairing">
将 Slack 用户配对到 Gateway 网关。
</Card>
<Card title="Groups" icon="users" href="/zh-CN/channels/groups">
<Card title="群组" icon="users" href="/zh-CN/channels/groups">
渠道和群组私信行为。
</Card>
<Card title="Channel routing" icon="route" href="/zh-CN/channels/channel-routing">
<Card title="渠道路由" icon="route" href="/zh-CN/channels/channel-routing">
将入站消息路由到智能体。
</Card>
<Card title="Security" icon="shield" href="/zh-CN/gateway/security">
<Card title="安全" icon="shield" href="/zh-CN/gateway/security">
威胁模型和加固。
</Card>
<Card title="Configuration" icon="sliders" href="/zh-CN/gateway/configuration">
<Card title="配置" icon="sliders" href="/zh-CN/gateway/configuration">
配置布局和优先级。
</Card>
<Card title="Slash commands" icon="terminal" href="/zh-CN/tools/slash-commands">
<Card title="Slash 命令" icon="terminal" href="/zh-CN/tools/slash-commands">
命令目录和行为。
</Card>
</CardGroup>

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

@ -1,102 +1,102 @@
---
read_when:
- 你想在 OpenClaw 中使用 OpenAI 模型
- 你想使用 Codex 订阅认证，而不是 API 密钥
- 你想使用 Codex 订阅身份验证，而不是 API 密钥
- 你需要更严格的 GPT-5 智能体执行行为
summary: 在 OpenClaw 中通过 API 密钥或 Codex 订阅使用 OpenAI
title: OpenAI
x-i18n:
generated_at: "2026-04-28T12:02:17Z"
generated_at: "2026-04-30T13:51:17Z"
model: gpt-5.5
provider: openai
source_hash: be0e2cd14990a53533c800cd8d305c9c50b0fa7131f6638e7b9d8dd9f2942fe8
source_hash: 7e113f2418f82a8859f208f85efb55114bda7bc17beeb28f012b19e861609dad
source_path: providers/openai.md
workflow: 16
---
OpenAI 提供面向 GPT 模型的开发者 API，Codex 也可以通过 OpenAI 的 Codex 客户端作为
ChatGPT 套餐中的编程智能体使用。OpenClaw 将这些
表面分开，以便配置保持可预测。
OpenAI 为 GPT 模型提供开发者 API，而 Codex 也可通过 OpenAI 的 Codex 客户端作为
ChatGPT 套餐中的编码智能体使用。OpenClaw 将这些
表面保持分离，让配置保持可预测。
OpenClaw 支持三条 OpenAI 系列路线。模型前缀选择
提供商/凭证路线；单独的运行时设置选择谁来执行
OpenClaw 支持三条 OpenAI 系列路由。模型前缀会选择
提供商/认证路由；单独的运行时设置会选择由谁执行
嵌入式 Agent loop：
- **API 密钥** — 使用按量计费的直接 OpenAI Platform 访问（`openai/*` 模型）
- **通过 PI 使用 Codex 订阅** — 使用订阅访问的 ChatGPT/Codex 登录（`openai-codex/*` 模型）
- **API key** — 使用按量计费的直接 OpenAI Platform 访问（`openai/*` 模型）
- **通过 PI 使用 Codex 订阅** — 使用订阅访问权限登录 ChatGPT/Codex（`openai-codex/*` 模型）
- **Codex app-server harness** — 原生 Codex app-server 执行（`openai/*` 模型加 `agents.defaults.agentRuntime.id: "codex"`）
OpenAI 明确支持在外部工具和 OpenClaw 这类工作流中使用订阅 OAuth。
OpenAI 明确支持在 OpenClaw 等外部工具和工作流中使用订阅 OAuth。
提供商、模型、运行时和渠道是分开的层。如果这些标签
混在一起，请先阅读 [Agent Runtimes](/zh-CN/concepts/agent-runtimes)，再
提供商、模型、运行时和渠道是分离的层。如果这些标签
被混在一起，请先阅读 [Agent Runtimes](/zh-CN/concepts/agent-runtimes)，再
更改配置。
## 快速选择
| 目标 | 使用 | 备注 |
| 目标 | 使用 | 说明 |
| --------------------------------------------- | ------------------------------------------------ | ---------------------------------------------------------------------------- |
| 直接 API 密钥计费 | `openai/gpt-5.5` | 设置 `OPENAI_API_KEY` 或运行 OpenAI API 密钥新手引导。 |
| 使用 ChatGPT/Codex 订阅凭证的 GPT-5.5 | `openai-codex/gpt-5.5` | Codex OAuth 的默认 PI 路线。订阅设置的首选。 |
| 使用原生 Codex app-server 行为的 GPT-5.5 | `openai/gpt-5.5` 加 `agentRuntime.id: "codex"` | 为该模型引用强制使用 Codex app-server harness。 |
| 图像生成或编辑 | `openai/gpt-image-2` | 可配合 `OPENAI_API_KEY` 或 OpenAI Codex OAuth 使用。 |
| 透明背景图像 | `openai/gpt-image-1.5` | 使用 `outputFormat=png` 或 `webp`，并设置 `openai.background=transparent`。 |
| 直接 API key 计费 | `openai/gpt-5.5` | 设置 `OPENAI_API_KEY` 或运行 OpenAI API key 新手引导。 |
| 通过 ChatGPT/Codex 订阅认证使用 GPT-5.5 | `openai-codex/gpt-5.5` | Codex OAuth 的默认 PI 路由。订阅设置的首选。 |
| 通过原生 Codex app-server 行为使用 GPT-5.5 | `openai/gpt-5.5` 加 `agentRuntime.id: "codex"` | 为该模型引用强制使用 Codex app-server harness。 |
| 图像生成或编辑 | `openai/gpt-image-2` | 可与 `OPENAI_API_KEY` 或 OpenAI Codex OAuth 搭配使用。 |
| 透明背景图像 | `openai/gpt-image-1.5` | 使用 `outputFormat=png` 或 `webp` 以及 `openai.background=transparent`。 |
## 命名映射
这些名称相似，但不能互换：
这些名称相似，但不可互换：
| 你看到的名称 | 层 | 含义 |
| ---------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------- |
| `openai` | 提供商前缀 | 直接 OpenAI Platform API 路线。 |
| `openai-codex` | 提供商前缀 | 通过常规 OpenClaw PI runner 使用的 OpenAI Codex OAuth/订阅路线。 |
| `codex` 插件 | 插件 | 提供原生 Codex app-server 运行时和 `/codex` 聊天控制的内置 OpenClaw 插件。 |
| `agentRuntime.id: codex` | Agent 运行时 | 为嵌入式轮次强制使用原生 Codex app-server harness。 |
| `/codex ...` | 聊天命令集 | 从对话中绑定/控制 Codex app-server 线程。 |
| `runtime: "acp", agentId: "codex"` | ACP 会话路线 | 通过 ACP/acpx 运行 Codex 的显式回退路径。 |
| `openai` | 提供商前缀 | 直接 OpenAI Platform API 路由。 |
| `openai-codex` | 提供商前缀 | 通过普通 OpenClaw PI runner 使用的 OpenAI Codex OAuth/订阅路由。 |
| `codex` 插件 | 插件 | 内置 OpenClaw 插件，提供原生 Codex app-server 运行时和 `/codex` 聊天控制。 |
| `agentRuntime.id: codex` | 智能体运行时 | 为嵌入式轮次强制使用原生 Codex app-server harness。 |
| `/codex ...` | 聊天命令集 | 在对话中绑定/控制 Codex app-server 线程。 |
| `runtime: "acp", agentId: "codex"` | ACP 会话路由 | 通过 ACP/acpx 运行 Codex 的显式回退路径。 |
这意味着一个配置可以有意同时包含 `openai-codex/*` 和
`codex` 插件。当你希望通过 PI 使用 Codex OAuth，同时也希望
原生 `/codex` 聊天控制可用时，这是有效的。`openclaw doctor` 会对该
组合发出警告，以便你确认这是有意为之；它不会重写该配置。
原生 `/codex` 聊天控制可用时，这是有效的。`openclaw doctor` 会对这个
组合发出警告，方便你确认这是有意设置；它不会重写它。
<Note>
GPT-5.5 可通过直接 OpenAI Platform API 密钥访问和
订阅/OAuth 路线使用。直接 `OPENAI_API_KEY`
流量使用 `openai/gpt-5.5`，通过 PI 使用 Codex OAuth 时使用 `openai-codex/gpt-5.5`，或者
将 `openai/gpt-5.5` 与 `agentRuntime.id: "codex"` 一起用于原生 Codex
GPT-5.5 可通过直接 OpenAI Platform API key 访问和
订阅/OAuth 路由使用。将 `openai/gpt-5.5` 用于直接 `OPENAI_API_KEY`
流量，将 `openai-codex/gpt-5.5` 用于通过 PI 使用 Codex OAuth，或将
`openai/gpt-5.5` 与 `agentRuntime.id: "codex"` 搭配，用于原生 Codex
app-server harness。
</Note>
<Note>
启用 OpenAI 插件，或选择 `openai-codex/*` 模型，并不会
启用内置 Codex app-server 插件。OpenClaw 只会在你明确通过
`agentRuntime.id: "codex"` 选择原生 Codex harness，或使用旧版 `codex/*` 模型引用时
启用内置 Codex app-server 插件。OpenClaw 只会在你通过
`agentRuntime.id: "codex"` 显式选择原生 Codex harness，或使用旧版 `codex/*` 模型引用时
启用该插件。
如果内置 `codex` 插件已启用，但 `openai-codex/*` 仍通过 PI 解析，
`openclaw doctor` 会发出警告并保持路线不变。
`openclaw doctor` 会发出警告并保持路由不变。
</Note>
## OpenClaw 功能覆盖
## OpenClaw 功能覆盖范围
| OpenAI 能力 | OpenClaw 表面 | Status |
| ------------------------- | ---------------------------------------------------------- | ------------------------------------------------------ |
| 聊天 / Responses | `openai/<model>` 模型提供商 | 是 |
| Codex 订阅模型 | 使用 `openai-codex` OAuth 的 `openai-codex/<model>` | 是 |
| Codex app-server harness | 使用 `agentRuntime.id: codex` 的 `openai/<model>` | 是 |
| 服务端 Web 搜索 | 原生 OpenAI Responses 工具 | 是，在启用 Web 搜索且未固定提供商时 |
| 服务端 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"` / Control UI Talk | 是 |
| 嵌入 | 记忆嵌入提供商 | 是 |
| Embeddings | 记忆 embedding 提供商 | 是 |
## 记忆嵌入
## 记忆 embeddings
OpenClaw 可以使用 OpenAI 或 OpenAI 兼容的嵌入端点，为
`memory_search` 索引和查询嵌入提供支持：
OpenClaw 可以使用 OpenAI 或 OpenAI 兼容的 embedding 端点，为
`memory_search` 索引和查询 embeddings 提供支持：
```json5
{
@ -111,55 +111,54 @@ OpenClaw 可以使用 OpenAI 或 OpenAI 兼容的嵌入端点，为
}
```
对于需要非对称嵌入标签的 OpenAI 兼容端点，请在
对于需要非对称 embedding 标签的 OpenAI 兼容端点，请在
`memorySearch` 下设置 `queryInputType` 和 `documentInputType`。OpenClaw 会将
它们作为提供商特定的 `input_type` 请求字段转发：查询嵌入使用
`queryInputType`；已索引的记忆片段和批量索引使用
`documentInputType`。完整示例请参阅 [记忆配置参考](/zh-CN/reference/memory-config#provider-specific-config)。
它们作为提供商特定的 `input_type` 请求字段转发：查询 embeddings 使用
`queryInputType`；已索引的记忆块和批量索引使用
`documentInputType`。完整示例见 [记忆配置参考](/zh-CN/reference/memory-config#provider-specific-config)。
## 入门指南
选择你偏好的凭证方法并按照设置步骤操作。
选择你偏好的认证方法并按照设置步骤操作。
<Tabs>
<Tab title="API key (OpenAI Platform)">
<Tab title="API key（OpenAI Platform）">
**最适合：** 直接 API 访问和按量计费。
<Steps>
<Step title="Get your API key">
从 [OpenAI Platform dashboard](https://platform.openai.com/api-keys) 创建或复制 API 密钥。
<Step title="获取你的 API key">
从 [OpenAI Platform dashboard](https://platform.openai.com/api-keys) 创建或复制 API key。
</Step>
<Step title="Run onboarding">
<Step title="运行新手引导">
```bash
openclaw onboard --auth-choice openai-api-key
```
或直接传入密钥：
或直接传入该 key：
```bash
openclaw onboard --openai-api-key "$OPENAI_API_KEY"
```
</Step>
<Step title="Verify the model is available">
<Step title="验证模型可用">
```bash
openclaw models list --provider openai
```
</Step>
</Steps>
### 路线摘要
### 路由摘要
| 模型引用 | 运行时配置 | 路线 | 凭证 |
| 模型引用 | 运行时配置 | 路由 | 认证 |
| ---------------------- | -------------------------- | --------------------------- | ---------------- |
| `openai/gpt-5.5` | 省略 / `agentRuntime.id: "pi"` | 直接 OpenAI Platform API | `OPENAI_API_KEY` |
| `openai/gpt-5.4-mini` | 省略 / `agentRuntime.id: "pi"` | 直接 OpenAI Platform API | `OPENAI_API_KEY` |
| `openai/gpt-5.5` | `agentRuntime.id: "codex"` | Codex app-server harness | Codex app-server |
<Note>
`openai/*` 是直接 OpenAI API 密钥路线，除非你明确强制使用
Codex app-server harness。通过默认 PI runner 使用 Codex OAuth 时使用 `openai-codex/*`，
或将 `openai/gpt-5.5` 与
`agentRuntime.id: "codex"` 一起用于原生 Codex app-server 执行。
除非你显式强制使用 Codex app-server harness，否则 `openai/*` 是直接 OpenAI API key 路由。将 `openai-codex/*` 用于通过
默认 PI runner 使用 Codex OAuth，或将 `openai/gpt-5.5` 与
`agentRuntime.id: "codex"` 搭配，用于原生 Codex app-server 执行。
</Note>
### 配置示例
@ -172,16 +171,16 @@ OpenClaw 可以使用 OpenAI 或 OpenAI 兼容的嵌入端点，为
```
<Warning>
OpenClaw **不**公开 `openai/gpt-5.3-codex-spark`。实时 OpenAI API 请求会拒绝该模型，当前 Codex 目录也没有公开它。
OpenClaw **不会** 暴露 `openai/gpt-5.3-codex-spark`。实时 OpenAI API 请求会拒绝该模型，当前 Codex 目录也不会暴露它。
</Warning>
</Tab>
<Tab title="Codex subscription">
**最适合：** 使用你的 ChatGPT/Codex 订阅，而不是单独的 API 密钥。Codex cloud 需要 ChatGPT 登录。
<Tab title="Codex 订阅">
**最适合：** 使用你的 ChatGPT/Codex 订阅，而不是单独的 API key。Codex cloud 需要 ChatGPT 登录。
<Steps>
<Step title="Run Codex OAuth">
<Step title="运行 Codex OAuth">
```bash
openclaw onboard --auth-choice openai-codex
```
@ -192,44 +191,39 @@ OpenClaw 可以使用 OpenAI 或 OpenAI 兼容的嵌入端点，为
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
```
</Step>
<Step title="Set the default model">
<Step title="设置默认模型">
```bash
openclaw config set agents.defaults.model.primary openai-codex/gpt-5.5
```
</Step>
<Step title="Verify the model is available">
<Step title="验证模型可用">
```bash
openclaw models list --provider openai-codex
```
</Step>
</Steps>
### 路线摘要
### 路由摘要
| 模型引用 | 运行时配置 | 路线 | 凭证 |
| 模型引用 | 运行时配置 | 路由 | 认证 |
|-----------|----------------|-------|------|
| `openai-codex/gpt-5.5` | 省略 / `runtime: "pi"` | 通过 PI 使用 ChatGPT/Codex OAuth | Codex 登录 |
| `openai-codex/gpt-5.5` | `runtime: "auto"` | 除非插件明确声明 `openai-codex`，否则仍使用 PI | Codex 登录 |
| `openai/gpt-5.5` | `agentRuntime.id: "codex"` | Codex app-server harness | Codex app-server 凭证 |
| `openai-codex/gpt-5.4-mini` | 省略 / `runtime: "pi"` | 通过 PI 使用 ChatGPT/Codex OAuth | Codex 登录 |
| `openai-codex/gpt-5.5` | `runtime: "auto"` | 仍为 PI，除非某个插件显式声明 `openai-codex` | Codex 登录 |
| `openai/gpt-5.5` | `agentRuntime.id: "codex"` | Codex app-server harness | Codex app-server 认证 |
<Note>
凭证/配置档命令继续使用 `openai-codex` 提供商 id。
`openai-codex/*` 模型前缀也是 Codex OAuth 的显式 PI 路线。
继续使用 `openai-codex` 提供商 ID 执行认证/配置文件命令。
`openai-codex/*` 模型前缀也是 Codex OAuth 的显式 PI 路由。
它不会选择或自动启用内置 Codex app-server harness。
</Note>
<Warning>
`openai-codex/gpt-5.4-mini` 不是受支持的 Codex OAuth 路线。请使用
带 OpenAI API 密钥的 `openai/gpt-5.4-mini`，或使用
带 Codex OAuth 的 `openai-codex/gpt-5.5`。
</Warning>
### 配置示例
```json5
@ -239,33 +233,33 @@ OpenClaw 可以使用 OpenAI 或 OpenAI 兼容的嵌入端点，为
```
<Note>
新手引导不再从 `~/.codex` 导入 OAuth 材料。请使用浏览器 OAuth（默认）或上面的设备码流程登录，OpenClaw 会在自己的智能体凭证存储中管理生成的凭证。
新手引导不再从 `~/.codex` 导入 OAuth 材料。请使用浏览器 OAuth（默认）或上面的设备码流程登录，OpenClaw 会在自己的智能体认证存储中管理生成的凭证。
</Note>
### Status 指示器
Chat `/status` 会显示当前会话正在使用哪个模型运行时。
默认 Pi harness 会显示为 `Runtime: OpenClaw Pi Default`。选择内置的 Codex app-server harness 时，`/status` 会显示
`Runtime: OpenAI Codex`。现有会话会保留已记录的 harness id，所以如果你希望 `/status` 在更改 `agentRuntime` 后反映新的 Pi/Codex 选择，请使用
聊天中的 `/status` 会显示当前会话正在使用哪个模型运行时。
默认 PI 运行框架显示为 `Runtime: OpenClaw Pi Default`。选择内置的 Codex app-server harness 时，`/status` 会显示
`Runtime: OpenAI Codex`。现有会话会保留其记录的 harness id，因此如果你希望 `/status` 反映新的 PI/Codex 选择，请在更改 `agentRuntime` 后使用
`/new` 或 `/reset`。
### Doctor 警告
如果启用了内置 `codex` 插件，同时选择了此标签页的
`openai-codex/*` 路由，`openclaw doctor` 会警告该模型仍会通过 PI 解析。当这是预期的订阅身份验证路由时，请保持配置不变。只有当你想要原生 Codex
app-server 执行时，才切换到 `openai/<model>` 并设置
如果启用了内置的 `codex` 插件，同时选择了此标签页的
`openai-codex/*` 路由，`openclaw doctor` 会警告该模型仍然通过 PI 解析。当这是预期的订阅凭证路由时，请保持配置不变。只有在你希望使用原生 Codex
app-server 执行时，才切换到 `openai/<model>` 加
`agentRuntime.id: "codex"`。
### 上下文窗口上限
OpenClaw 将模型元数据和运行时上下文上限视为两个独立值。
OpenClaw 将模型元数据和运行时上下文上限视为独立值。
对于通过 Codex OAuth 使用的 `openai-codex/gpt-5.5`：
- 原生 `contextWindow`：`1000000`
- 默认运行时 `contextTokens` 上限：`272000`
较小的默认上限在实践中具有更好的延迟和质量特性。可使用 `contextTokens` 覆盖它：
实践中，较小的默认上限具有更好的延迟和质量特征。使用 `contextTokens` 覆盖它：
```json5
{
@ -285,37 +279,37 @@ OpenClaw 可以使用 OpenAI 或 OpenAI 兼容的嵌入端点，为
### 目录恢复
当存在上游 Codex 目录元数据时，OpenClaw 会将其用于 `gpt-5.5`。如果实时 Codex 设备发现缺少 `openai-codex/gpt-5.5` 行，而账户已完成身份验证，OpenClaw 会合成该 OAuth 模型行，确保 cron、子智能体和已配置的默认模型运行不会因 `Unknown model` 而失败。
当上游 Codex 目录元数据中存在 `gpt-5.5` 时，OpenClaw 会使用它。如果实时 Codex 发现遗漏了 `openai-codex/gpt-5.5` 行，但账户已通过凭证验证，OpenClaw 会合成该 OAuth 模型行，使 cron、子智能体和已配置的默认模型运行不会因
`Unknown model` 而失败。
</Tab>
</Tabs>
## 原生 Codex app-server 身份验证
## 原生 Codex app-server 凭证
原生 Codex app-server harness 使用 `openai/*` 模型引用以及
`agentRuntime.id: "codex"`，但其身份验证仍基于账户。OpenClaw 按以下顺序选择身份验证：
原生 Codex app-server harness 使用 `openai/*` 模型引用加
`agentRuntime.id: "codex"`，但其凭证仍然基于账户。OpenClaw 按以下顺序选择凭证：
1. 绑定到智能体的显式 OpenClaw `openai-codex` 身份验证配置文件。
1. 绑定到智能体的显式 OpenClaw `openai-codex` 凭证配置文件。
2. app-server 的现有账户，例如本地 Codex CLI ChatGPT 登录。
3. 仅对本地 stdio app-server 启动，当 app-server 报告没有账户但仍需要 OpenAI 身份验证时，先使用 `CODEX_API_KEY`，再使用
`OPENAI_API_KEY`。
3. 仅对于本地 stdio app-server 启动，当 app-server 报告无账户但仍需要 OpenAI 凭证时，依次使用 `CODEX_API_KEY`、`OPENAI_API_KEY`。
这意味着本地 ChatGPT/Codex 订阅登录不会仅因为 Gateway 网关进程也有用于直接 OpenAI 模型或嵌入的 `OPENAI_API_KEY` 而被替换。环境 API key 回退仅适用于本地 stdio 无账户路径；它不会发送到 WebSocket app-server 连接。选择订阅式 Codex 配置文件时，OpenClaw 还会避免将 `CODEX_API_KEY` 和 `OPENAI_API_KEY` 放入派生的 stdio app-server 子进程，并通过 app-server 登录 RPC 发送所选凭证。
这意味着本地 ChatGPT/Codex 订阅登录不会仅仅因为 Gateway 网关进程也为直接 OpenAI 模型或嵌入设置了 `OPENAI_API_KEY` 而被替换。环境变量 API key 回退仅适用于本地 stdio 无账户路径；它不会发送到 WebSocket app-server 连接。选择订阅式 Codex 配置文件时，OpenClaw 还会避免将 `CODEX_API_KEY` 和 `OPENAI_API_KEY` 传入派生的 stdio app-server 子进程，并通过 app-server 登录 RPC 发送所选凭证。
## 图像生成
内置 `openai` 插件通过 `image_generate` 工具注册图像生成。
它通过同一个 `openai/gpt-image-2` 模型引用，同时支持 OpenAI API key 图像生成和 Codex OAuth 图像生成。
内置的 `openai` 插件通过 `image_generate` 工具注册图像生成。
它通过相同的 `openai/gpt-image-2` 模型引用，同时支持 OpenAI API key 图像生成和 Codex OAuth 图像生成。
| 能力 | OpenAI API key | Codex OAuth |
| ------------------------- | ---------------------------------- | ------------------------------------ |
| 模型引用 | `openai/gpt-image-2` | `openai/gpt-image-2` |
| 身份验证 | `OPENAI_API_KEY` | OpenAI Codex OAuth 登录 |
| 传输 | OpenAI Images API | Codex Responses 后端 |
| 凭证 | `OPENAI_API_KEY` | OpenAI Codex OAuth 登录 |
| 传输协议 | OpenAI Images API | Codex Responses 后端 |
| 每次请求的最大图像数 | 4 | 4 |
| 编辑模式 | 已启用（最多 5 张参考图像） | 已启用（最多 5 张参考图像） |
| 尺寸覆盖 | 支持，包括 2K/4K 尺寸 | 支持，包括 2K/4K 尺寸 |
| 宽高比 / 分辨率 | 不转发到 OpenAI Images API | 在安全时映射到受支持的尺寸 |
| 宽高比 / 分辨率 | 不转发到 OpenAI Images API | 安全时映射到受支持的尺寸 |
```json5
{
@ -328,18 +322,18 @@ OpenClaw 可以使用 OpenAI 或 OpenAI 兼容的嵌入端点，为
```
<Note>
请参阅[图像生成](/zh-CN/tools/image-generation)，了解共享工具参数、提供商选择和故障转移行为。
参阅[图像生成](/zh-CN/tools/image-generation)，了解共享工具参数、提供商选择和故障转移行为。
</Note>
`gpt-image-2` 是 OpenAI 文本转图像生成和图像编辑的默认值。`gpt-image-1.5`、`gpt-image-1` 和 `gpt-image-1-mini` 仍可作为显式模型覆盖使用。透明背景 PNG/WebP 输出请使用 `openai/gpt-image-1.5`；当前 `gpt-image-2` API 会拒绝
`gpt-image-2` 是 OpenAI 文本到图像生成和图像编辑的默认模型。`gpt-image-1.5`、`gpt-image-1` 和 `gpt-image-1-mini` 仍可用作显式模型覆盖。透明背景 PNG/WebP 输出请使用 `openai/gpt-image-1.5`；当前 `gpt-image-2` API 会拒绝
`background: "transparent"`。
对于透明背景请求，智能体应调用 `image_generate`，并设置
`model: "openai/gpt-image-1.5"`、`outputFormat: "png"` 或 `"webp"`，以及
`background: "transparent"`；旧的 `openai.background` 提供商选项仍被接受。OpenClaw 还会保护公开 OpenAI 和
OpenAI Codex OAuth 路由，将默认 `openai/gpt-image-2` 透明请求重写为 `gpt-image-1.5`；Azure 和自定义 OpenAI 兼容端点会保留其已配置的部署/模型名称。
`background: "transparent"`；较旧的 `openai.background` 提供商选项仍被接受。OpenClaw 还会保护公开 OpenAI 和
OpenAI Codex OAuth 路由，将默认的 `openai/gpt-image-2` 透明请求重写为 `gpt-image-1.5`；Azure 和自定义 OpenAI 兼容端点会保留其已配置的部署/模型名称。
同一设置也会暴露给无头 CLI 运行：
同一设置也暴露给无头 CLI 运行：
```bash
openclaw infer image generate \
@ -350,14 +344,12 @@ openclaw infer image generate \
--json
```
从输入文件开始时，请将相同的 `--output-format` 和 `--background` 标志用于
`openclaw infer image edit`。
`--openai-background` 仍可用作 OpenAI 专用别名。
从输入文件开始时，请对 `openclaw infer image edit` 使用相同的 `--output-format` 和 `--background` 标志。
`--openai-background` 仍可作为 OpenAI 专用别名使用。
对于 Codex OAuth 安装，请保留相同的 `openai/gpt-image-2` 引用。配置了
`openai-codex` OAuth 配置文件时，OpenClaw 会解析存储的 OAuth 访问令牌，并通过 Codex Responses 后端发送图像请求。它不会先尝试 `OPENAI_API_KEY`，也不会对该请求静默回退到 API key。当你想改用直接 OpenAI Images API 路由时，请显式配置 `models.providers.openai`，并提供 API key、自定义基础 URL 或 Azure 端点。
如果该自定义图像端点位于受信任的 LAN/私有地址，还要设置
`browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true`；除非存在此选择加入项，否则 OpenClaw 会继续阻止私有/内部 OpenAI 兼容图像端点。
对于 Codex OAuth 安装，请保持相同的 `openai/gpt-image-2` 引用。配置 `openai-codex` OAuth 配置文件后，OpenClaw 会解析该已存储的 OAuth 访问令牌，并通过 Codex Responses 后端发送图像请求。对于该请求，它不会先尝试 `OPENAI_API_KEY`，也不会静默回退到 API key。若你希望改用直接 OpenAI Images API 路由，请使用 API key、自定义基础 URL 或 Azure 端点显式配置 `models.providers.openai`。
如果该自定义图像端点位于受信任的 LAN/私有地址，还请设置
`browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true`；除非存在此选择加入设置，否则 OpenClaw 会继续阻止私有/内部 OpenAI 兼容图像端点。
生成：
@ -379,15 +371,15 @@ openclaw infer image generate \
## 视频生成
内置 `openai` 插件通过 `video_generate` 工具注册视频生成。
内置的 `openai` 插件通过 `video_generate` 工具注册视频生成。
| 能力 | 值 |
| ---------------- | --------------------------------------------------------------------------------- |
| 默认模型 | `openai/sora-2` |
| 模式 | 文本转视频、图像转视频、单视频编辑 |
| 模式 | 文本到视频、图像到视频、单视频编辑 |
| 参考输入 | 1 张图像或 1 个视频 |
| 尺寸覆盖 | 支持 |
| 其他覆盖 | `aspectRatio`、`resolution`、`audio`、`watermark` 会被忽略，并产生工具警告 |
| 其他覆盖 | `aspectRatio`、`resolution`、`audio`、`watermark` 会被忽略并显示工具警告 |
```json5
{
@ -400,22 +392,22 @@ openclaw infer image generate \
```
<Note>
请参阅[视频生成](/zh-CN/tools/video-generation)，了解共享工具参数、提供商选择和故障转移行为。
参阅[视频生成](/zh-CN/tools/video-generation)，了解共享工具参数、提供商选择和故障转移行为。
</Note>
## GPT-5 提示词贡献
## GPT-5 提示贡献
OpenClaw 会为跨提供商的 GPT-5 系列运行添加共享 GPT-5 提示词贡献。它按模型 id 应用，因此 `openai-codex/gpt-5.5`、`openai/gpt-5.5`、`openrouter/openai/gpt-5.5`、`opencode/gpt-5.5` 以及其他兼容的 GPT-5 引用会收到相同叠加。旧版 GPT-4.x 模型不会收到。
OpenClaw 会为跨提供商的 GPT-5 系列运行添加共享 GPT-5 提示贡献。它按模型 id 应用，因此 `openai-codex/gpt-5.5`、`openai/gpt-5.5`、`openrouter/openai/gpt-5.5`、`opencode/gpt-5.5` 和其他兼容的 GPT-5 引用都会收到相同的覆盖。较旧的 GPT-4.x 模型不会收到。
内置原生 Codex harness 通过 Codex app-server developer instructions 使用相同的 GPT-5 行为和心跳叠加，因此即便 harness 提示词的其余部分由 Codex 拥有，被强制通过 `agentRuntime.id: "codex"` 运行的 `openai/gpt-5.x` 会话仍会保留相同的跟进执行和主动心跳指导。
内置的原生 Codex harness 会通过 Codex app-server 开发者指令使用相同的 GPT-5 行为和 Heartbeat 覆盖，因此通过 `agentRuntime.id: "codex"` 强制运行的 `openai/gpt-5.x` 会话，即使 Codex 拥有其余 harness 提示，也会保留相同的跟进执行和主动 Heartbeat 指引。
GPT-5 贡献会为 persona 持久性、执行安全、工具纪律、输出形态、完成检查和验证添加带标签的行为契约。特定渠道的回复和静默消息行为保留在共享 OpenClaw 系统提示词和出站投递策略中。GPT-5 指导始终会为匹配模型启用。友好的交互风格层是独立的，并且可配置。
GPT-5 贡献会添加带标签的行为契约，涵盖人格持久性、执行安全、工具纪律、输出形态、完成检查和验证。渠道特定的回复和静默消息行为保留在共享 OpenClaw 系统提示和出站投递策略中。GPT-5 指引始终为匹配模型启用。友好的交互风格层是独立且可配置的。
| 值 | 效果 |
| ---------------------- | ---------------------------------- |
| `"friendly"`（默认） | 启用友好的交互风格层 |
| `"on"` | `"friendly"` 的别名 |
| `"off"` | 仅禁用友好风格层 |
| 值 | 效果 |
| ---------------------- | ---------------------------- |
| `"friendly"`（默认） | 启用友好交互风格层 |
| `"on"` | `"friendly"` 的别名 |
| `"off"` | 仅禁用友好风格层 |
<Tabs>
<Tab title="配置">
@ -439,30 +431,30 @@ GPT-5 贡献会为 persona 持久性、执行安全、工具纪律、输出形
</Tabs>
<Tip>
值在运行时不区分大小写，因此 `"Off"` 和 `"off"` 都会禁用友好风格层。
这些值在运行时不区分大小写，因此 `"Off"` 和 `"off"` 都会禁用友好风格层。
</Tip>
<Note>
当共享的 `agents.defaults.promptOverlays.gpt5.personality` 设置未设置时，仍会读取旧版 `plugins.entries.openai.config.personality` 作为兼容性回退。
当未设置共享的 `agents.defaults.promptOverlays.gpt5.personality` 设置时，仍会读取旧版 `plugins.entries.openai.config.personality` 作为兼容性回退。
</Note>
## 语音和语音识别
<AccordionGroup>
<Accordion title="语音合成 (TTS)">
内置 `openai` 插件为 `messages.tts` 表面注册语音合成。
<Accordion title="语音合成（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 key | `messages.tts.providers.openai.apiKey` | 回退到 `OPENAI_API_KEY` |
| 基础 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
{
@ -477,21 +469,20 @@ GPT-5 贡献会为 persona 持久性、执行安全、工具纪律、输出形
```
<Note>
设置 `OPENAI_TTS_BASE_URL` 可覆盖 TTS 基础 URL，且不会影响聊天 API 端点。
设置 `OPENAI_TTS_BASE_URL` 可覆盖 TTS 基础 URL，而不影响聊天 API 端点。
</Note>
</Accordion>
<Accordion title="语音转文本">
内置 `openai` 插件通过 OpenClaw 的媒体理解转写表面注册批量语音转文本。
内置的 `openai` 插件通过 OpenClaw 的媒体理解转录表面注册批量语音转文本。
- 默认模型：`gpt-4o-transcribe`
- 端点：OpenAI REST `/v1/audio/transcriptions`
- 输入路径：multipart 音频文件上传
- 在 OpenClaw 中，凡是入站音频转写使用
`tools.media.audio` 的位置都支持，包括 Discord 语音渠道片段和渠道音频附件
- 只要入站音频转录使用 `tools.media.audio`，OpenClaw 都支持该功能，包括 Discord 语音频道片段和渠道音频附件
要强制将 OpenAI 用于入站音频转录：
要强制对入站音频转录使用 OpenAI：
```json5
{
@ -511,7 +502,7 @@ GPT-5 贡献会为 persona 持久性、执行安全、工具纪律、输出形
}
```
如果共享音频媒体配置或每次调用的转录请求提供了语言和提示词提示，它们会转发给 OpenAI。
当共享音频媒体配置或单次转录请求提供语言和提示词提示时，它们会转发给 OpenAI。
</Accordion>
@ -525,10 +516,10 @@ GPT-5 贡献会为 persona 持久性、执行安全、工具纪律、输出形
| 提示词 | `...openai.prompt` | （未设置） |
| 静音时长 | `...openai.silenceDurationMs` | `800` |
| VAD 阈值 | `...openai.vadThreshold` | `0.5` |
| API 密钥 | `...openai.apiKey` | 回退到 `OPENAI_API_KEY` |
| API key | `...openai.apiKey` | 回退到 `OPENAI_API_KEY` |
<Note>
使用 WebSocket 连接到 `wss://api.openai.com/v1/realtime`，音频格式为 G.711 u-law（`g711_ulaw` / `audio/pcmu`）。此流式传输提供商用于语音通话的实时转录路径；Discord 语音目前会录制短片段，并改用批量 `tools.media.audio` 转录路径。
使用 WebSocket 连接到 `wss://api.openai.com/v1/realtime`，并使用 G.711 u-law（`g711_ulaw` / `audio/pcmu`）音频。这个流式提供商用于语音通话的实时转录路径；Discord 语音目前会录制短片段，并改用批处理 `tools.media.audio` 转录路径。
</Note>
</Accordion>
@ -543,14 +534,14 @@ GPT-5 贡献会为 persona 持久性、执行安全、工具纪律、输出形
| 温度 | `...openai.temperature` | `0.8` |
| VAD 阈值 | `...openai.vadThreshold` | `0.5` |
| 静音时长 | `...openai.silenceDurationMs` | `500` |
| API 密钥 | `...openai.apiKey` | 回退到 `OPENAI_API_KEY` |
| API key | `...openai.apiKey` | 回退到 `OPENAI_API_KEY` |
<Note>
通过 `azureEndpoint` 和 `azureDeployment` 配置键支持用于后端实时桥接的 Azure OpenAI。支持双向工具调用。使用 G.711 u-law 音频格式。
</Note>
<Note>
Control UI 通话使用 OpenAI 浏览器实时会话，并通过 Gateway 网关铸造的临时客户端密钥以及浏览器与 OpenAI Realtime API 的直接 WebRTC SDP 交换来运行。维护者可以用 `OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts` 做实时验证；OpenAI 这一路会在 Node 中铸造客户端密钥，使用模拟麦克风媒体生成浏览器 SDP offer，将其发送到 OpenAI，并应用 SDP answer，且不会记录密钥。
Control UI Talk 使用 OpenAI 浏览器实时会话，其中包含由 Gateway 网关签发的临时客户端密钥，并让浏览器直接通过 WebRTC SDP 与 OpenAI Realtime API 交换。维护者可使用 `OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts` 进行实时验证；OpenAI 这一段会在 Node 中签发客户端密钥，使用虚拟麦克风媒体生成浏览器 SDP offer，将其发送到 OpenAI，并在不记录密钥的情况下应用 SDP answer。
</Note>
</Accordion>
@ -558,21 +549,21 @@ GPT-5 贡献会为 persona 持久性、执行安全、工具纪律、输出形
## Azure OpenAI 端点
内置的 `openai` 提供商可以通过覆盖基础 URL，将图像生成目标指向 Azure OpenAI 资源。在图像生成路径上，OpenClaw 会检测 `models.providers.openai.baseUrl` 上的 Azure 主机名，并自动切换到 Azure 的请求形态。
内置的 `openai` provider 可以通过覆盖基础 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` 影响。请参阅 [语音与语音合成](#voice-and-speech) 下的 **实时语音** 折叠项了解其 Azure 设置。
</Note>
在以下情况使用 Azure OpenAI：
- 你已经有 Azure OpenAI 订阅、配额或企业协议
- 你需要 Azure 提供的区域数据驻留或合规控制
- 你想将流量保留在现有 Azure 租户内
- 你希望将流量保留在现有 Azure 租户内
### 配置
要通过内置 `openai` 提供商使用 Azure 图像生成，请将 `models.providers.openai.baseUrl` 指向你的 Azure 资源，并将 `apiKey` 设置为 Azure OpenAI 密钥（不是 OpenAI Platform 密钥）：
要通过内置的 `openai` provider 使用 Azure 图像生成，请将 `models.providers.openai.baseUrl` 指向你的 Azure 资源，并将 `apiKey` 设置为 Azure OpenAI 密钥（不是 OpenAI Platform 密钥）：
```json5
{
@ -587,28 +578,28 @@ GPT-5 贡献会为 persona 持久性、执行安全、工具纪律、输出形
}
```
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}/...`）
- 使用按部署限定范围的路径（`/openai/deployments/{deployment}/...`）
- 向每个请求追加 `?api-version=...`
- 对 Azure 图像生成调用使用 600 秒默认请求超时。每次调用的 `timeoutMs` 值仍会覆盖此默认值。
- 对 Azure 图像生成调用使用 600 秒的默认请求超时。单次调用的 `timeoutMs` 值仍会覆盖此默认值。
其他基础 URL（公共 OpenAI、兼容 OpenAI 的代理）会保留标准 OpenAI 图像请求形态。
其他基础 URL（公共 OpenAI、兼容 OpenAI 的代理）会保留标准 OpenAI 图像请求格式。
<Note>
`openai` 提供商的图像生成路径中的 Azure 路由需要 OpenClaw 2026.4.22 或更高版本。早期版本会将任何自定义 `openai.baseUrl` 当作公共 OpenAI 端点处理，并且在 Azure 图像部署上会失败。
`openai` provider 图像生成路径的 Azure 路由需要 OpenClaw 2026.4.22 或更高版本。早期版本会把任何自定义 `openai.baseUrl` 当作公共 OpenAI 端点处理，并且在访问 Azure 图像部署时失败。
</Note>
### API 版本
设置 `AZURE_OPENAI_API_VERSION`，为 Azure 图像生成路径固定特定的 Azure 预览版或 GA 版本：
设置 `AZURE_OPENAI_API_VERSION`，为 Azure 图像生成路径固定特定的 Azure 预览版或正式版：
```bash
export AZURE_OPENAI_API_VERSION="2024-12-01-preview"
@ -618,45 +609,45 @@ export AZURE_OPENAI_API_VERSION="2024-12-01-preview"
### 模型名称就是部署名称
Azure OpenAI 会将模型绑定到部署。对于通过内置 `openai` 提供商路由的 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
```
同样的部署名称规则也适用于通过内置 `openai` 提供商路由的图像生成调用。
同样的部署名称规则也适用于通过内置 `openai` provider 路由的图像生成调用。
### 区域可用性
Azure 图像生成目前仅在部分区域可用（例如 `eastus2`、`swedencentral`、`polandcentral`、`westus3`、`uaenorth`）。创建部署前，请检查 Microsoft 当前的区域列表，并确认你的区域提供具体模型。
Azure 图像生成目前仅在部分区域可用（例如 `eastus2`、`swedencentral`、`polandcentral`、`westus3`、`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 的路由** 折叠项。
Azure OpenAI 使用原生传输和兼容行为，但不会收到 OpenClaw 的隐藏归因标头 — 请参阅 [高级配置](#advanced-configuration) 下的 **原生与兼容 OpenAI 的路由** 折叠项。
对于 Azure 上的聊天或 Responses 流量（图像生成以外），请使用新手引导流程或专用 Azure 提供商配置——仅设置 `openai.baseUrl` 不会启用 Azure API/认证形态。另有单独的 `azure-openai-responses/*` 提供商；请参阅下面的服务器端压缩折叠项。
对于 Azure 上的聊天或 Responses 流量（图像生成以外），请使用新手引导流程或专用 Azure provider 配置 — 仅设置 `openai.baseUrl` 不会套用 Azure API/认证格式。存在一个单独的 `azure-openai-responses/*` provider；请参阅下方的服务端压缩折叠项。
</Note>
## 高级配置
<AccordionGroup>
<Accordion title="传输（WebSocket 与 SSE）">
对于 `openai/*` 和 `openai-codex/*`，OpenClaw 都会优先使用 WebSocket，并以 SSE 作为回退（`"auto"`）。
OpenClaw 对 `openai/*` 和 `openai-codex/*` 都优先使用 WebSocket，并带有 SSE 回退（`"auto"`）。
在 `"auto"` 模式下，OpenClaw 会：
- 在回退到 SSE 前，重试一次早期 WebSocket 失败
在 `"auto"` 模式下，OpenClaw：
- 在回退到 SSE 之前重试一次早期 WebSocket 失败
- 失败后，将 WebSocket 标记为降级约 60 秒，并在冷却期间使用 SSE
- 为重试和重新连接附加稳定的会话与轮次身份标头
- 在不同传输变体之间规范化用量计数器（`input_tokens` / `prompt_tokens`）
| 值 | 行为 |
|-------|----------|
| `"auto"`（默认） | WebSocket 优先，SSE 回退 |
| `"auto"`（默认） | 优先 WebSocket，回退到 SSE |
| `"sse"` | 仅强制使用 SSE |
| `"websocket"` | 仅强制使用 WebSocket |
@ -679,15 +670,15 @@ Azure OpenAI 使用原生传输和兼容行为，但不会接收 OpenClaw 的隐
相关 OpenAI 文档：
- [使用 WebSocket 的 Realtime API](https://platform.openai.com/docs/guides/realtime-websocket)
- [流式传输 API 响应（SSE）](https://platform.openai.com/docs/guides/streaming-responses)
- [流式 API 响应（SSE）](https://platform.openai.com/docs/guides/streaming-responses)
</Accordion>
<Accordion title="WebSocket 预热">
OpenClaw 默认为 `openai/*` 和 `openai-codex/*` 启用 WebSocket 预热，以减少首轮延迟。
OpenClaw 默认为 `openai/*` 和 `openai-codex/*` 启用 WebSocket 预热，以降低首轮延迟。
```json5
// Disable warm-up
// 禁用预热
{
agents: {
defaults: {
@ -709,7 +700,7 @@ Azure OpenAI 使用原生传输和兼容行为，但不会接收 OpenClaw 的隐
- **聊天/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
{
@ -724,13 +715,13 @@ Azure OpenAI 使用原生传输和兼容行为，但不会接收 OpenClaw 的隐
```
<Note>
会话覆盖优先于配置。在 Sessions UI 中清除会话覆盖后，会话会回到配置的默认值。
会话覆盖优先于配置。在会话 UI 中清除会话覆盖后，该会话会回到配置的默认值。
</Note>
</Accordion>
<Accordion title="优先处理（service_tier）">
OpenAI 的 API 通过 `service_tier` 暴露优先处理。在 OpenClaw 中按模型设置：
<Accordion title="优先级处理（service_tier）">
OpenAI 的 API 通过 `service_tier` 暴露优先级处理。在 OpenClaw 中按模型设置它：
```json5
{
@ -747,23 +738,23 @@ Azure OpenAI 使用原生传输和兼容行为，但不会接收 OpenClaw 的隐
支持的值：`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`）。如果你通过代理路由任一 provider，OpenClaw 会保持 `service_tier` 不变。
</Warning>
</Accordion>
<Accordion title="服务器端压缩（Responses API）">
对于直接 OpenAI Responses 模型（`api.openai.com` 上的 `openai/*`），OpenAI 插件的 Pi harness 流包装器会自动启用服务器端压缩：
<Accordion title="服务端压缩（Responses API）">
对于直接的 OpenAI Responses 模型（`api.openai.com` 上的 `openai/*`），OpenAI 插件的 Pi harness 流包装器会自动启用服务端压缩：
- 强制 `store: true`（除非模型兼容性设置了 `supportsStore: false`）
- 强制 `store: true`（除非模型兼容性设置 `supportsStore: false`）
- 注入 `context_management: [{ type: "compaction", compact_threshold: ... }]`
- 默认 `compact_threshold`：`contextWindow` 的 70%（不可用时为 `80000`）
这适用于内置 Pi harness 路径，也适用于嵌入式运行使用的 OpenAI 提供商钩子。原生 Codex 应用服务器 harness 通过 Codex 管理自己的上下文，并使用 `agents.defaults.agentRuntime.id` 单独配置。
这适用于内置 Pi harness 路径，也适用于嵌入式运行使用的 OpenAI provider 钩子。原生 Codex 应用服务器 harness 通过 Codex 管理自己的上下文，并使用 `agents.defaults.agentRuntime.id` 单独配置。
<Tabs>
<Tab title="显式启用">
适用于 Azure OpenAI Responses 等兼容端点：
对兼容端点（如 Azure OpenAI Responses）有用：
```json5
{
@ -815,13 +806,13 @@ Azure OpenAI 使用原生传输和兼容行为，但不会接收 OpenClaw 的隐
</Tabs>
<Note>
`responsesServerCompaction` 只控制 `context_management` 注入。直接的 OpenAI Responses 模型仍会强制使用 `store: true`，除非 compat 设置了 `supportsStore: false`。
`responsesServerCompaction` 仅控制 `context_management` 注入。直接的 OpenAI Responses 模型仍会强制使用 `store: true`，除非 compat 设置了 `supportsStore: false`。
</Note>
</Accordion>
<Accordion title="Strict-agentic GPT 模式">
对于 `openai/*` 上的 GPT-5 系列运行，OpenClaw 可以使用更严格的嵌入式执行契约：
<Accordion title="严格智能体式 GPT 模式">
对于在 `openai/*` 上运行的 GPT-5 系列，OpenClaw 可以使用更严格的嵌入式执行契约：
```json5
{
@ -834,13 +825,13 @@ Azure OpenAI 使用原生传输和兼容行为，但不会接收 OpenClaw 的隐
```
使用 `strict-agentic` 时，OpenClaw：
- 当有工具操作可用时，不再将仅计划的轮次视为成功推进
- 使用立即行动引导重试该轮次
- 当工具操作可用时，不再将仅有计划的轮次视为成功推进
- 使用立即行动 steer 重试该轮次
- 对实质性工作自动启用 `update_plan`
- 如果模型持续计划而不行动，则显示明确的受阻状态
- 如果模型持续规划而不行动，则显示明确的阻塞状态
<Note>
仅限 OpenAI 和 Codex GPT-5 系列运行。其他提供商和更旧的模型系列保持默认行为。
仅限 OpenAI 和 Codex GPT-5 系列运行。其他提供商和较旧的模型系列保持默认行为。
</Note>
</Accordion>
@ -850,24 +841,24 @@ Azure OpenAI 使用原生传输和兼容行为，但不会接收 OpenClaw 的隐
**原生路由**（`openai/*`、Azure OpenAI）：
- 仅对支持 OpenAI `none` effort 的模型保留 `reasoning: { effort: "none" }`
- 对会拒绝 `reasoning.effort: "none"` 的模型或代理省略已禁用的 reasoning
- 对拒绝 `reasoning.effort: "none"` 的模型或代理省略禁用的推理
- 默认将工具 schema 设为严格模式
- 仅在经过验证的原生主机上附加隐藏归因标头
- 保留仅 OpenAI 使用的请求整形（`service_tier`、`store`、reasoning-compat、prompt-cache 提示）
- 仅在已验证的原生主机上附加隐藏归因标头
- 保留仅限 OpenAI 的请求整形（`service_tier`、`store`、reasoning-compat、prompt-cache 提示）
**代理/兼容路由：**
- 使用更宽松的 compat 行为
- 从非原生 `openai-completions` 载荷中移除 Completions `store`
- 接受用于 OpenAI 兼容 Completions 代理的高级 `params.extra_body`/`params.extraBody` 透传 JSON
- 接受用于 vLLM 等 OpenAI 兼容 Completions 代理的 `params.chat_template_kwargs`
- 不强制使用严格工具 schema 或仅原生路由使用的标头
- 接受用于 OpenAI 兼容 Completions 代理（例如 vLLM）的 `params.chat_template_kwargs`
- 不强制使用严格工具 schema 或仅限原生的标头
Azure OpenAI 使用原生传输和 compat 行为，但不会接收隐藏归因标头。
Azure OpenAI 使用原生传输和 compat 行为，但不会收到隐藏归因标头。
</Accordion>
</AccordionGroup>
## 相关
## 相关内容
<CardGroup cols={2}>
<Card title="模型选择" href="/zh-CN/concepts/model-providers" icon="layers">