chore(i18n): refresh zh-CN translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
97fb35fe50
commit
41324cec2b
@ -1,49 +1,51 @@
|
||||
---
|
||||
read_when:
|
||||
- 你想在 OpenClaw 中使用 OpenAI 模型
|
||||
- 你想使用 Codex 订阅认证，而不是 API 密钥
|
||||
- 你希望使用 Codex 订阅认证，而不是 API 密钥
|
||||
- 你需要更严格的 GPT-5 智能体执行行为
|
||||
summary: 在 OpenClaw 中使用 OpenAI 的 API 密钥或 Codex 订阅
|
||||
summary: 在 OpenClaw 中通过 API 密钥或 Codex 订阅使用 OpenAI
|
||||
title: OpenAI
|
||||
x-i18n:
|
||||
generated_at: "2026-04-24T02:20:29Z"
|
||||
generated_at: "2026-04-24T02:36:59Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: f9bb65b29be2b69a85663b17a68560c557ffb5303ac7afa2b27548a27397af46
|
||||
source_hash: 8337990d0de692b32746b05ab344695fc5a54ab3855993ac7795fabf38d4d19d
|
||||
source_path: providers/openai.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
OpenAI 为 GPT 模型提供开发者 API。OpenClaw 支持三种 OpenAI 系列路由。模型前缀决定所使用的路由：
|
||||
OpenAI 为 GPT 模型提供开发者 API。OpenClaw 支持三种 OpenAI 系列接入方式。模型前缀决定所使用的接入方式：
|
||||
|
||||
- **API 密钥** — 通过按量计费直接访问 OpenAI Platform（`openai/*` 模型）
|
||||
- **通过 PI 的 Codex 订阅** — 使用 ChatGPT/Codex 登录并通过订阅访问（`openai-codex/*` 模型）
|
||||
- **Codex app-server harness** — 原生 Codex app-server 执行（`openai/*` 模型，并配合 `agents.defaults.embeddedHarness.runtime: "codex"`）
|
||||
- **Codex app-server harness** — 原生 Codex app-server 执行（`openai/*` 模型，外加 `agents.defaults.embeddedHarness.runtime: "codex"`）
|
||||
|
||||
OpenAI 明确支持在像 OpenClaw 这样的外部工具和工作流中使用基于订阅的 OAuth。
|
||||
OpenAI 明确支持在 OpenClaw 这样的外部工具和工作流中使用基于订阅的 OAuth。
|
||||
|
||||
<Note>
|
||||
GPT-5.5 目前在 OpenClaw 中可通过订阅 / OAuth 路由使用：
|
||||
`openai-codex/gpt-5.5` 配合 PI runner，或 `openai/gpt-5.5` 配合
|
||||
Codex app-server harness。一旦 OpenAI 在公共 API 上启用 GPT-5.5，即可支持通过 API 密钥直接访问 `openai/gpt-5.5`；
|
||||
在此之前，对于 `OPENAI_API_KEY` 配置，请使用支持 API 的模型，例如 `openai/gpt-5.4`。
|
||||
GPT-5.5 目前可通过 OpenClaw 中基于订阅 / OAuth 的接入方式使用：
|
||||
使用 PI runner 时为
|
||||
`openai-codex/gpt-5.5`，使用
|
||||
Codex app-server harness 时为 `openai/gpt-5.5`。
|
||||
`openai/gpt-5.5` 的直接 API 密钥访问会在 OpenAI 在公共 API 上启用 GPT-5.5 后得到支持；在此之前，请在
|
||||
`OPENAI_API_KEY` 配置中使用已支持 API 的模型，例如 `openai/gpt-5.4`。
|
||||
</Note>
|
||||
|
||||
## OpenClaw 功能覆盖范围
|
||||
|
||||
| OpenAI 能力 | OpenClaw 界面 | 状态 |
|
||||
| ------------------------- | ------------------------------------------------------ | ------------------------------------------------------ |
|
||||
| OpenAI 能力 | OpenClaw 表面 | 状态 |
|
||||
| ------------------------- | ---------------------------------------------------------- | ------------------------------------------------------ |
|
||||
| 聊天 / Responses | `openai/<model>` 模型提供商 | 是 |
|
||||
| Codex 订阅模型 | 使用 `openai-codex` OAuth 的 `openai-codex/<model>` | 是 |
|
||||
| Codex app-server harness | 使用 `embeddedHarness.runtime: codex` 的 `openai/<model>` | 是 |
|
||||
| 服务端网页搜索 | 原生 OpenAI Responses 工具 | 是，在启用网页搜索且未固定提供商时 |
|
||||
| Codex 订阅模型 | 带 `openai-codex` OAuth 的 `openai-codex/<model>` | 是 |
|
||||
| Codex app-server harness | 带 `embeddedHarness.runtime: codex` 的 `openai/<model>` | 是 |
|
||||
| 服务端 web 搜索 | 原生 OpenAI Responses 工具 | 是，启用 web 搜索且未固定提供商时 |
|
||||
| 图像 | `image_generate` | 是 |
|
||||
| 视频 | `video_generate` | 是 |
|
||||
| 文本转语音 | `messages.tts.provider: "openai"` / `tts` | 是 |
|
||||
| 批量语音转文本 | `tools.media.audio` / 媒体理解 | 是 |
|
||||
| 流式语音转文本 | 语音通话 `streaming.provider: "openai"` | 是 |
|
||||
| 实时语音 | 语音通话 `realtime.provider: "openai"` | 是 |
|
||||
| Embeddings | memory embedding 提供商 | 是 |
|
||||
| 实时语音 | 语音通话 `realtime.provider: "openai"` / 控制 UI Talk | 是 |
|
||||
| Embeddings | memory embedding provider | 是 |
|
||||
|
||||
## 入门指南
|
||||
|
||||
@ -51,18 +53,18 @@ Codex app-server harness。一旦 OpenAI 在公共 API 上启用 GPT-5.5，即
|
||||
|
||||
<Tabs>
|
||||
<Tab title="API 密钥（OpenAI Platform）">
|
||||
**最适合：** 直接访问 API 和按量计费。
|
||||
**最适合：** 直接 API 访问和按量计费。
|
||||
|
||||
<Steps>
|
||||
<Step title="获取你的 API 密钥">
|
||||
在 [OpenAI Platform 控制台](https://platform.openai.com/api-keys) 创建或复制一个 API 密钥。
|
||||
在 [OpenAI Platform 仪表板](https://platform.openai.com/api-keys) 中创建或复制一个 API 密钥。
|
||||
</Step>
|
||||
<Step title="运行新手引导">
|
||||
```bash
|
||||
openclaw onboard --auth-choice openai-api-key
|
||||
```
|
||||
|
||||
或直接传入密钥：
|
||||
或者直接传入密钥：
|
||||
|
||||
```bash
|
||||
openclaw onboard --openai-api-key "$OPENAI_API_KEY"
|
||||
@ -75,18 +77,16 @@ Codex app-server harness。一旦 OpenAI 在公共 API 上启用 GPT-5.5，即
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
### 路由摘要
|
||||
### 接入方式摘要
|
||||
|
||||
| 模型引用 | 路由 | 认证 |
|
||||
| Model ref | 接入方式 | 认证 |
|
||||
|-----------|-------|------|
|
||||
| `openai/gpt-5.4` | 直接 OpenAI Platform API | `OPENAI_API_KEY` |
|
||||
| `openai/gpt-5.4-mini` | 直接 OpenAI Platform API | `OPENAI_API_KEY` |
|
||||
| `openai/gpt-5.5` | 一旦 OpenAI 在 API 上启用 GPT-5.5 后的未来直接 API 路由 | `OPENAI_API_KEY` |
|
||||
| `openai/gpt-5.5` | 未来当 OpenAI 在 API 上启用 GPT-5.5 后可直接通过 API 使用 | `OPENAI_API_KEY` |
|
||||
|
||||
<Note>
|
||||
`openai/*` 默认是直接 OpenAI API 密钥路由，除非你显式强制使用
|
||||
Codex app-server harness。GPT-5.5 本身目前仅支持订阅 / OAuth；
|
||||
对于通过默认 PI runner 使用的 Codex OAuth，请使用 `openai-codex/*`。
|
||||
除非你明确强制使用 Codex app-server harness，否则 `openai/*` 就是直接的 OpenAI API 密钥接入方式。GPT-5.5 本身目前仅支持订阅 / OAuth；如需通过默认 PI runner 使用 Codex OAuth，请使用 `openai-codex/*`。
|
||||
</Note>
|
||||
|
||||
### 配置示例
|
||||
@ -99,7 +99,7 @@ Codex app-server harness。一旦 OpenAI 在公共 API 上启用 GPT-5.5，即
|
||||
```
|
||||
|
||||
<Warning>
|
||||
OpenClaw **不**提供 `openai/gpt-5.3-codex-spark`。实际的 OpenAI API 请求会拒绝该模型，当前 Codex 目录也同样未提供它。
|
||||
OpenClaw **不**提供 `openai/gpt-5.3-codex-spark`。实时 OpenAI API 请求会拒绝该模型，当前 Codex 目录也同样未提供它。
|
||||
</Warning>
|
||||
|
||||
</Tab>
|
||||
@ -119,7 +119,7 @@ Codex app-server harness。一旦 OpenAI 在公共 API 上启用 GPT-5.5，即
|
||||
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
|
||||
@ -137,16 +137,15 @@ Codex app-server harness。一旦 OpenAI 在公共 API 上启用 GPT-5.5，即
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
### 路由摘要
|
||||
### 接入方式摘要
|
||||
|
||||
| 模型引用 | 路由 | 认证 |
|
||||
| Model ref | 接入方式 | 认证 |
|
||||
|-----------|-------|------|
|
||||
| `openai-codex/gpt-5.5` | 通过 PI 的 ChatGPT/Codex OAuth | Codex 登录 |
|
||||
| `openai/gpt-5.5` + `embeddedHarness.runtime: "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 路径。
|
||||
</Note>
|
||||
|
||||
### 配置示例
|
||||
@ -158,17 +157,14 @@ Codex app-server harness。一旦 OpenAI 在公共 API 上启用 GPT-5.5，即
|
||||
```
|
||||
|
||||
<Note>
|
||||
新手引导不再从 `~/.codex` 导入 OAuth 材料。请使用浏览器 OAuth（默认）或上述设备码流程登录——OpenClaw 会在它自己的智能体认证存储中管理生成的凭证。
|
||||
新手引导不再从 `~/.codex` 导入 OAuth 材料。请使用浏览器 OAuth（默认）或上述设备码流程登录——OpenClaw 会在自己的智能体认证存储中管理生成的凭证。
|
||||
</Note>
|
||||
|
||||
### 状态指示器
|
||||
|
||||
聊天中的 `/status` 会显示当前会话正在使用哪个嵌入式 harness。
|
||||
默认的 PI harness 显示为 `Runner: pi (embedded)`，且不会
|
||||
额外添加单独标记。选择内置的 Codex app-server harness 时，
|
||||
`/status` 会在 `Fast` 后附加非 PI harness id，例如
|
||||
`Fast · codex`。现有会话会保留其记录的 harness id，因此如果你在修改
|
||||
`embeddedHarness` 后希望 `/status` 反映新的 PI/Codex 选择，请使用
|
||||
聊天中的 `/status` 会显示当前
|
||||
会话正在使用哪个 embedded harness。默认的 PI harness 显示为 `Runner: pi (embedded)`，不会额外添加单独的标记。选择内置的 Codex app-server harness 时，`/status` 会在 `Fast` 后追加非 PI harness id，例如
|
||||
`Fast · codex`。现有会话会保留其记录的 harness id，因此如果你在更改 `embeddedHarness` 后希望 `/status` 反映新的 PI / Codex 选择，请使用
|
||||
`/new` 或 `/reset`。
|
||||
|
||||
### 上下文窗口上限
|
||||
@ -180,7 +176,7 @@ Codex app-server harness。一旦 OpenAI 在公共 API 上启用 GPT-5.5，即
|
||||
- 原生 `contextWindow`：`1000000`
|
||||
- 默认运行时 `contextTokens` 上限：`272000`
|
||||
|
||||
在实际使用中，较小的默认上限通常具有更好的延迟和质量表现。你可以通过 `contextTokens` 覆盖它：
|
||||
较小的默认上限在实践中通常具有更好的延迟和质量表现。你可以通过 `contextTokens` 覆盖它：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -195,7 +191,7 @@ Codex app-server harness。一旦 OpenAI 在公共 API 上启用 GPT-5.5，即
|
||||
```
|
||||
|
||||
<Note>
|
||||
使用 `contextWindow` 声明模型的原生元数据。使用 `contextTokens` 限制运行时上下文预算。
|
||||
使用 `contextWindow` 声明模型原生元数据。使用 `contextTokens` 限制运行时上下文预算。
|
||||
</Note>
|
||||
|
||||
</Tab>
|
||||
@ -204,17 +200,18 @@ Codex app-server harness。一旦 OpenAI 在公共 API 上启用 GPT-5.5，即
|
||||
## 图像生成
|
||||
|
||||
内置的 `openai` 插件通过 `image_generate` 工具注册图像生成功能。
|
||||
它支持使用同一个 `openai/gpt-image-2` 模型引用，同时进行基于 OpenAI API 密钥的图像生成和基于 Codex OAuth 的图像生成。
|
||||
它同时支持基于 OpenAI API 密钥的图像生成和基于 Codex OAuth 的图像生成，
|
||||
两者都使用同一个 `openai/gpt-image-2` 模型引用。
|
||||
|
||||
| 能力 | OpenAI API 密钥 | Codex OAuth |
|
||||
| ------------------------- | ---------------------------------- | ------------------------------------ |
|
||||
| 模型引用 | `openai/gpt-image-2` | `openai/gpt-image-2` |
|
||||
| Model ref | `openai/gpt-image-2` | `openai/gpt-image-2` |
|
||||
| 认证 | `OPENAI_API_KEY` | OpenAI Codex OAuth 登录 |
|
||||
| 传输 | OpenAI Images API | Codex Responses 后端 |
|
||||
| 每次请求最大图像数 | 4 | 4 |
|
||||
| 编辑模式 | 已启用（最多 5 张参考图像） | 已启用（最多 5 张参考图像） |
|
||||
| 尺寸覆盖 | 支持，包括 2K/4K 尺寸 | 支持，包括 2K/4K 尺寸 |
|
||||
| 宽高比 / 分辨率 | 不会转发到 OpenAI Images API | 在安全情况下映射为受支持的尺寸 |
|
||||
| 每次请求的最大图像数量 | 4 | 4 |
|
||||
| 编辑模式 | 已启用（最多 5 张参考图） | 已启用（最多 5 张参考图） |
|
||||
| 尺寸覆盖 | 支持，包括 2K / 4K 尺寸 | 支持，包括 2K / 4K 尺寸 |
|
||||
| 宽高比 / 分辨率 | 不会转发到 OpenAI Images API | 在安全时映射到受支持的尺寸 |
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -230,29 +227,28 @@ Codex app-server harness。一旦 OpenAI 在公共 API 上启用 GPT-5.5，即
|
||||
有关共享工具参数、提供商选择和故障切换行为，请参阅 [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`。
|
||||
|
||||
对于 Codex OAuth 安装，请继续使用相同的 `openai/gpt-image-2` 引用。
|
||||
当配置了 `openai-codex` OAuth 配置文件时，OpenClaw 会解析该存储的 OAuth
|
||||
对于 Codex OAuth 安装，请继续使用相同的 `openai/gpt-image-2` 引用。配置了
|
||||
`openai-codex` OAuth 配置文件后，OpenClaw 会解析该已存储的 OAuth
|
||||
访问令牌，并通过 Codex Responses 后端发送图像请求。它不会先尝试 `OPENAI_API_KEY`，也不会为该请求静默回退到 API 密钥。
|
||||
当你希望改为使用直接 OpenAI Images API 路由时，请显式配置
|
||||
`models.providers.openai`，提供 API 密钥、自定义 base URL 或 Azure 端点。
|
||||
如果该自定义图像端点位于受信任的局域网 / 私有地址上，还需设置
|
||||
`browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true`；除非提供此显式启用项，
|
||||
否则 OpenClaw 会继续阻止私有 / 内部的兼容 OpenAI 图像端点。
|
||||
当你希望改用直接 OpenAI Images API
|
||||
路径时，请为 `models.providers.openai` 显式配置 API 密钥、
|
||||
自定义 base URL 或 Azure endpoint。
|
||||
如果该自定义图像端点位于受信任的 LAN / 私有地址上，还需设置
|
||||
`browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true`；除非显式选择启用此项，
|
||||
否则 OpenClaw 会继续阻止私有 / 内部的 OpenAI 兼容图像端点。
|
||||
|
||||
生成：
|
||||
|
||||
```
|
||||
/tool image_generate model=openai/gpt-image-2 prompt="为 macOS 上的 OpenClaw 制作一张精致的发布海报" 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
|
||||
```
|
||||
|
||||
## 视频生成
|
||||
@ -263,9 +259,9 @@ OpenAI 图像工作流应使用 `openai/gpt-image-2`。
|
||||
| ---------------- | --------------------------------------------------------------------------------- |
|
||||
| 默认模型 | `openai/sora-2` |
|
||||
| 模式 | 文生视频、图生视频、单视频编辑 |
|
||||
| 参考输入 | 1 张图像或 1 个视频 |
|
||||
| 参考输入 | 1 张图片或 1 个视频 |
|
||||
| 尺寸覆盖 | 支持 |
|
||||
| 其他覆盖项 | `aspectRatio`、`resolution`、`audio`、`watermark` 会被忽略，并显示工具警告 |
|
||||
| 其他覆盖 | `aspectRatio`、`resolution`、`audio`、`watermark` 会被忽略，并产生工具警告 |
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -283,15 +279,15 @@ OpenAI 图像工作流应使用 `openai/gpt-image-2`。
|
||||
|
||||
## GPT-5 提示词贡献
|
||||
|
||||
OpenClaw 会为跨提供商的 GPT-5 系列运行添加一个共享的 GPT-5 提示词贡献。它按模型 id 应用，因此 `openai-codex/gpt-5.5`、`openai/gpt-5.4`、`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.4`、`openrouter/openai/gpt-5.5`、`opencode/gpt-5.5` 以及其他兼容的 GPT-5 引用都会接收相同的覆盖层。较旧的 GPT-4.x 模型则不会。
|
||||
|
||||
内置的原生 Codex harness 通过 Codex app-server 开发者指令使用相同的 GPT-5 行为和心跳叠加层，因此，即使 Codex 接管了 harness 提示词的其余部分，强制通过 `embeddedHarness.runtime: "codex"` 的 `openai/gpt-5.x` 会话仍会保持相同的后续执行和主动心跳指引。
|
||||
内置的原生 Codex harness 通过 Codex app-server 开发者指令使用相同的 GPT-5 行为和 heartbeat 覆盖层，因此，即使 Codex 接管了 harness 提示词的其余部分，强制通过 `embeddedHarness.runtime: "codex"` 的 `openai/gpt-5.x` 会话仍会保留相同的后续执行和主动 heartbeat 指导。
|
||||
|
||||
GPT-5 提示词贡献增加了一个带标签的行为契约，涵盖 persona 持续性、执行安全性、工具纪律、输出形状、完成检查和验证。渠道特定的回复和静默消息行为仍保留在共享的 OpenClaw 系统提示词和出站传递策略中。GPT-5 指引始终会为匹配的模型启用。友好的交互风格层是独立的，并且可配置。
|
||||
GPT-5 提示词贡献添加了一个带标记的行为契约，涵盖 persona 持续性、执行安全、工具纪律、输出形态、完成检查和验证。渠道特定的回复和静默消息行为仍保留在共享的 OpenClaw 系统提示词和出站投递策略中。GPT-5 指导会始终对匹配的模型启用。友好交互风格层是单独的，并且可配置。
|
||||
|
||||
| 值 | 效果 |
|
||||
| ---------------------- | ------------------------------------------- |
|
||||
| `"friendly"`（默认） | 启用友好的交互风格层 |
|
||||
| `"friendly"`（默认） | 启用友好交互风格层 |
|
||||
| `"on"` | `"friendly"` 的别名 |
|
||||
| `"off"` | 仅禁用友好风格层 |
|
||||
|
||||
@ -321,22 +317,22 @@ GPT-5 提示词贡献增加了一个带标签的行为契约，涵盖 persona
|
||||
</Tip>
|
||||
|
||||
<Note>
|
||||
当未设置共享的 `agents.defaults.promptOverlays.gpt5.personality` 配置时，仍会读取旧版的 `plugins.entries.openai.config.personality` 作为兼容性回退。
|
||||
旧版 `plugins.entries.openai.config.personality` 仍会作为兼容性回退项被读取，前提是未设置共享的 `agents.defaults.promptOverlays.gpt5.personality`。
|
||||
</Note>
|
||||
|
||||
## 语音与语音处理
|
||||
## 语音和语音识别
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="语音合成（TTS）">
|
||||
内置的 `openai` 插件为 `messages.tts` 界面注册了语音合成功能。
|
||||
内置的 `openai` 插件为 `messages.tts` 表面注册了语音合成功能。
|
||||
|
||||
| 设置 | 配置路径 | 默认值 |
|
||||
|---------|------------|---------|
|
||||
| 模型 | `messages.tts.providers.openai.model` | `gpt-4o-mini-tts` |
|
||||
| 音色 | `messages.tts.providers.openai.voice` | `coral` |
|
||||
| 速度 | `messages.tts.providers.openai.speed` | （未设置） |
|
||||
| 指令 | `messages.tts.providers.openai.instructions` | （未设置，仅 `gpt-4o-mini-tts`） |
|
||||
| 格式 | `messages.tts.providers.openai.responseFormat` | 语音便笺为 `opus`，文件为 `mp3` |
|
||||
| 指令 | `messages.tts.providers.openai.instructions` | （未设置，仅适用于 `gpt-4o-mini-tts`） |
|
||||
| 格式 | `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` |
|
||||
|
||||
@ -362,13 +358,13 @@ GPT-5 提示词贡献增加了一个带标签的行为契约，涵盖 persona
|
||||
|
||||
<Accordion title="语音转文本">
|
||||
内置的 `openai` 插件通过
|
||||
OpenClaw 的媒体理解转录界面注册了批量语音转文本功能。
|
||||
OpenClaw 的媒体理解转录表面注册了批量语音转文本功能。
|
||||
|
||||
- 默认模型：`gpt-4o-transcribe`
|
||||
- 端点：OpenAI REST `/v1/audio/transcriptions`
|
||||
- 输入路径：multipart 音频文件上传
|
||||
- 在 OpenClaw 中，凡是入站音频转录使用
|
||||
`tools.media.audio` 的地方都支持，包括 Discord 语音频道片段和渠道
|
||||
- 在 OpenClaw 中，只要入站音频转录使用
|
||||
`tools.media.audio`，就可得到支持，包括 Discord 语音频道片段和渠道
|
||||
音频附件
|
||||
|
||||
要强制将 OpenAI 用于入站音频转录：
|
||||
@ -391,31 +387,31 @@ GPT-5 提示词贡献增加了一个带标签的行为契约，涵盖 persona
|
||||
}
|
||||
```
|
||||
|
||||
当由共享音频媒体配置或按次转录请求提供语言和提示词提示时，
|
||||
这些信息会转发给 OpenAI。
|
||||
当共享音频媒体配置或按次调用的转录请求提供了语言和提示信息时，
|
||||
这些提示会被转发给 OpenAI。
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="实时转录">
|
||||
内置的 `openai` 插件为 Voice Call 插件注册了实时转录功能。
|
||||
内置的 `openai` 插件为语音通话插件注册了实时转录功能。
|
||||
|
||||
| 设置 | 配置路径 | 默认值 |
|
||||
|---------|------------|---------|
|
||||
| 模型 | `plugins.entries.voice-call.config.streaming.providers.openai.model` | `gpt-4o-transcribe` |
|
||||
| 语言 | `...openai.language` | （未设置） |
|
||||
| 提示词 | `...openai.prompt` | （未设置） |
|
||||
| 静音时长 | `...openai.silenceDurationMs` | `800` |
|
||||
| 提示 | `...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`）音频格式。这个流式提供商用于语音通话的实时转录路径；Discord 语音当前仍会录制短片段，并改用批量 `tools.media.audio` 转录路径。
|
||||
</Note>
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="实时语音">
|
||||
内置的 `openai` 插件为 Voice Call 插件注册了实时语音功能。
|
||||
内置的 `openai` 插件为语音通话插件注册了实时语音功能。
|
||||
|
||||
| 设置 | 配置路径 | 默认值 |
|
||||
|---------|------------|---------|
|
||||
@ -423,7 +419,7 @@ GPT-5 提示词贡献增加了一个带标签的行为契约，涵盖 persona
|
||||
| 音色 | `...openai.voice` | `alloy` |
|
||||
| Temperature | `...openai.temperature` | `0.8` |
|
||||
| VAD 阈值 | `...openai.vadThreshold` | `0.5` |
|
||||
| 静音时长 | `...openai.silenceDurationMs` | `500` |
|
||||
| 静默时长 | `...openai.silenceDurationMs` | `500` |
|
||||
| API 密钥 | `...openai.apiKey` | 回退到 `OPENAI_API_KEY` |
|
||||
|
||||
<Note>
|
||||
@ -435,27 +431,26 @@ GPT-5 提示词贡献增加了一个带标签的行为契约，涵盖 persona
|
||||
|
||||
## Azure OpenAI 端点
|
||||
|
||||
内置的 `openai` 提供商可以通过覆盖 base URL，将 Azure OpenAI 资源用作图像生成目标。在图像生成路径上，OpenClaw 会检测 `models.providers.openai.baseUrl` 上的 Azure 主机名，并自动切换到 Azure 的请求格式。
|
||||
内置的 `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) 下的 **实时语音**
|
||||
不受 `models.providers.openai.baseUrl` 影响。其 Azure 设置请参阅 [语音和语音识别](#voice-and-speech) 下 **实时语音**
|
||||
折叠项。
|
||||
</Note>
|
||||
|
||||
在以下情况下使用 Azure OpenAI：
|
||||
|
||||
- 你已经拥有 Azure OpenAI 订阅、配额或企业协议
|
||||
- 你已经有 Azure OpenAI 订阅、配额或企业协议
|
||||
- 你需要 Azure 提供的区域数据驻留或合规控制
|
||||
- 你希望将流量保留在现有的 Azure 租户内
|
||||
- 你希望将流量保留在现有 Azure 租户内
|
||||
|
||||
### 配置
|
||||
|
||||
对于通过内置 `openai` 提供商进行的 Azure 图像生成，请将
|
||||
`models.providers.openai.baseUrl` 指向你的 Azure 资源，并将 `apiKey`
|
||||
设置为 Azure OpenAI 密钥（而不是 OpenAI Platform 密钥）：
|
||||
`models.providers.openai.baseUrl` 指向你的 Azure 资源，并将 `apiKey` 设置为
|
||||
Azure OpenAI 密钥（不是 OpenAI Platform 密钥）：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -470,8 +465,7 @@ GPT-5 提示词贡献增加了一个带标签的行为契约，涵盖 persona
|
||||
}
|
||||
```
|
||||
|
||||
OpenClaw 会将以下 Azure 主机后缀识别为 Azure 图像生成
|
||||
路由：
|
||||
OpenClaw 会将以下 Azure 主机后缀识别为 Azure 图像生成接入方式：
|
||||
|
||||
- `*.openai.azure.com`
|
||||
- `*.services.ai.azure.com`
|
||||
@ -480,7 +474,7 @@ OpenClaw 会将以下 Azure 主机后缀识别为 Azure 图像生成
|
||||
对于发送到已识别 Azure 主机的图像生成请求，OpenClaw 会：
|
||||
|
||||
- 发送 `api-key` 请求头，而不是 `Authorization: Bearer`
|
||||
- 使用基于 deployment 的路径（`/openai/deployments/{deployment}/...`）
|
||||
- 使用按 deployment 限定的路径（`/openai/deployments/{deployment}/...`）
|
||||
- 为每个请求追加 `?api-version=...`
|
||||
|
||||
其他 base URL（公共 OpenAI、兼容 OpenAI 的代理）会继续使用标准的
|
||||
@ -488,29 +482,29 @@ OpenAI 图像请求格式。
|
||||
|
||||
<Note>
|
||||
`openai` 提供商图像生成路径的 Azure 路由要求
|
||||
OpenClaw 2026.4.22 或更高版本。更早版本会将任何自定义的
|
||||
`openai.baseUrl` 视为公共 OpenAI 端点，因此在 Azure
|
||||
OpenClaw 2026.4.22 或更高版本。更早的版本会将任何自定义
|
||||
`openai.baseUrl` 都视为公共 OpenAI 端点，因此在 Azure
|
||||
图像 deployment 上会失败。
|
||||
</Note>
|
||||
|
||||
### API 版本
|
||||
|
||||
设置 `AZURE_OPENAI_API_VERSION`，可为 Azure 图像生成路径固定特定的 Azure 预览版或 GA 版本：
|
||||
设置 `AZURE_OPENAI_API_VERSION` 可为 Azure 图像生成路径固定特定的 Azure 预览版或 GA 版本：
|
||||
|
||||
```bash
|
||||
export AZURE_OPENAI_API_VERSION="2024-12-01-preview"
|
||||
```
|
||||
|
||||
当该变量未设置时，默认值为 `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`、提供 `gpt-image-2` 的 deployment：
|
||||
如果你创建了一个名为 `gpt-image-2-prod`、用于提供 `gpt-image-2` 的 deployment：
|
||||
|
||||
```
|
||||
/tool image_generate model=openai/gpt-image-2-prod prompt="一张简洁的海报" size=1024x1024 count=1
|
||||
/tool image_generate model=openai/gpt-image-2-prod prompt="A clean poster" size=1024x1024 count=1
|
||||
```
|
||||
|
||||
同样的 deployment 名称规则也适用于通过内置 `openai` 提供商路由的图像生成调用。
|
||||
@ -519,38 +513,38 @@ Azure OpenAI 会将模型绑定到 deployment。对于通过内置 `openai` 提
|
||||
|
||||
Azure 图像生成目前仅在部分区域可用
|
||||
（例如 `eastus2`、`swedencentral`、`polandcentral`、`westus3`、
|
||||
`uaenorth`）。创建 deployment 之前，请先查看微软当前的区域列表，并确认你的区域提供相应的具体模型。
|
||||
`uaenorth`）。在创建 deployment 之前，请先查看 Microsoft 的最新区域列表，并确认你的区域提供了对应的具体模型。
|
||||
|
||||
### 参数差异
|
||||
|
||||
Azure OpenAI 和公共 OpenAI 并不总是接受相同的图像参数。
|
||||
Azure 可能会拒绝公共 OpenAI 允许的某些选项（例如 `gpt-image-2` 上的某些
|
||||
`background` 值），或者仅在特定模型版本上提供这些选项。这些差异来自 Azure 和底层模型，而不是 OpenClaw。如果 Azure 请求因验证错误而失败，请在 Azure 门户中检查你的具体 deployment 和 API 版本所支持的参数集。
|
||||
Azure 可能会拒绝公共 OpenAI 允许的某些选项（例如
|
||||
`gpt-image-2` 上的某些 `background` 值），或者仅在特定模型版本上提供它们。这些差异来自 Azure 和底层模型，而不是
|
||||
OpenClaw。如果 Azure 请求因验证错误而失败，请在
|
||||
Azure 门户中检查你的具体 deployment 和 API 版本所支持的参数集。
|
||||
|
||||
<Note>
|
||||
Azure OpenAI 使用原生传输和兼容行为，但不会接收
|
||||
OpenClaw 的隐藏归因请求头——请参阅 [高级配置](#advanced-configuration) 下的
|
||||
**原生与兼容 OpenAI 的路由**
|
||||
OpenClaw 的隐藏 attribution 请求头——请参阅 [高级配置](#advanced-configuration) 下 **原生与兼容 OpenAI 的接入方式**
|
||||
折叠项。
|
||||
|
||||
对于 Azure 上的聊天或 Responses 流量（除图像生成之外），请使用
|
||||
新手引导流程或专用的 Azure 提供商配置——仅设置 `openai.baseUrl`
|
||||
并不会自动使用 Azure 的 API / 认证格式。另有一个单独的
|
||||
`azure-openai-responses/*` 提供商；请参阅下方的
|
||||
服务端压缩折叠项。
|
||||
对于 Azure 上的聊天或 Responses 流量（不止图像生成），请使用
|
||||
新手引导流程或专用的 Azure provider 配置——仅设置 `openai.baseUrl`
|
||||
并不会自动采用 Azure 的 API / 认证格式。还存在一个单独的
|
||||
`azure-openai-responses/*` 提供商；请参阅下方的“服务端压缩”折叠项。
|
||||
</Note>
|
||||
|
||||
## 高级配置
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="传输（WebSocket 与 SSE）">
|
||||
OpenClaw 对 `openai/*` 和 `openai-codex/*` 都默认采用 WebSocket 优先、SSE 回退（`"auto"`）的方式。
|
||||
对于 `openai/*` 和 `openai-codex/*`，OpenClaw 都默认采用 WebSocket 优先、SSE 回退（`"auto"`）策略。
|
||||
|
||||
在 `"auto"` 模式下，OpenClaw 会：
|
||||
- 在回退到 SSE 之前，对一次早期 WebSocket 失败重试一次
|
||||
- 发生失败后，将 WebSocket 标记为降级约 60 秒，并在冷却期间使用 SSE
|
||||
- 为重试和重连附加稳定的会话和轮次身份请求头
|
||||
- 在不同传输变体之间统一使用量计数器（`input_tokens` / `prompt_tokens`）
|
||||
- 在回退到 SSE 之前，重试一次早期 WebSocket 失败
|
||||
- 失败后，将 WebSocket 标记为降级约 60 秒，并在冷却期间使用 SSE
|
||||
- 为重试和重连附加稳定的会话与轮次标识请求头
|
||||
- 在不同传输变体间标准化用量计数器（`input_tokens` / `prompt_tokens`）
|
||||
|
||||
| 值 | 行为 |
|
||||
|-------|----------|
|
||||
@ -576,13 +570,13 @@ OpenClaw 的隐藏归因请求头——请参阅 [高级配置](#advanced-config
|
||||
```
|
||||
|
||||
相关 OpenAI 文档：
|
||||
- [使用 WebSocket 的 Realtime API](https://platform.openai.com/docs/guides/realtime-websocket)
|
||||
- [流式 API 响应（SSE）](https://platform.openai.com/docs/guides/streaming-responses)
|
||||
- [Realtime API with WebSocket](https://platform.openai.com/docs/guides/realtime-websocket)
|
||||
- [Streaming API responses (SSE)](https://platform.openai.com/docs/guides/streaming-responses)
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="WebSocket 预热">
|
||||
OpenClaw 默认会为 `openai/*` 和 `openai-codex/*` 启用 WebSocket 预热，以减少首轮延迟。
|
||||
对于 `openai/*` 和 `openai-codex/*`，OpenClaw 默认启用 WebSocket 预热，以减少首轮延迟。
|
||||
|
||||
```json5
|
||||
// 禁用预热
|
||||
@ -602,12 +596,12 @@ OpenClaw 的隐藏归因请求头——请参阅 [高级配置](#advanced-config
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="快速模式">
|
||||
OpenClaw 为 `openai/*` 和 `openai-codex/*` 提供了一个共享的快速模式开关：
|
||||
OpenClaw 为 `openai/*` 和 `openai-codex/*` 提供了共享的快速模式开关：
|
||||
|
||||
- **聊天 / 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
|
||||
{
|
||||
@ -622,13 +616,13 @@ OpenClaw 的隐藏归因请求头——请参阅 [高级配置](#advanced-config
|
||||
```
|
||||
|
||||
<Note>
|
||||
会话覆盖优先于配置。在 Sessions UI 中清除会话覆盖后，该会话会恢复为配置的默认值。
|
||||
会话级覆盖优先于配置。在 Sessions UI 中清除会话级覆盖后，该会话会恢复为配置的默认值。
|
||||
</Note>
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="优先处理（service_tier）">
|
||||
OpenAI 的 API 通过 `service_tier` 提供优先处理。你可以在 OpenClaw 中按模型设置它：
|
||||
OpenAI 的 API 通过 `service_tier` 提供优先处理能力。你可以在 OpenClaw 中按模型设置它：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -645,23 +639,23 @@ OpenClaw 的隐藏归因请求头——请参阅 [高级配置](#advanced-config
|
||||
支持的值：`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/*`），OpenAI 插件的 Pi-harness 流包装器会自动启用服务端压缩：
|
||||
对于直接 OpenAI Responses 模型（位于 `api.openai.com` 的 `openai/*`），OpenAI 插件的 Pi-harness 流包装器会自动启用服务端压缩：
|
||||
|
||||
- 强制设置 `store: true`（除非模型兼容性设置了 `supportsStore: false`）
|
||||
- 注入 `context_management: [{ type: "compaction", compact_threshold: ... }]`
|
||||
- 默认 `compact_threshold`：`contextWindow` 的 70%（不可用时为 `80000`）
|
||||
|
||||
这适用于内置的 Pi harness 路径，以及嵌入式运行所使用的 OpenAI 提供商钩子。原生 Codex app-server harness 通过 Codex 自行管理上下文，并通过 `agents.defaults.embeddedHarness.runtime` 单独配置。
|
||||
这适用于内置的 Pi harness 路径，也适用于嵌入式运行所使用的 OpenAI provider hook。原生 Codex app-server harness 通过 Codex 自行管理上下文，并通过 `agents.defaults.embeddedHarness.runtime` 单独配置。
|
||||
|
||||
<Tabs>
|
||||
<Tab title="显式启用">
|
||||
对于 Azure OpenAI Responses 之类的兼容端点很有用：
|
||||
对于 Azure OpenAI Responses 等兼容端点，这会很有用：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -713,13 +707,13 @@ OpenClaw 的隐藏归因请求头——请参阅 [高级配置](#advanced-config
|
||||
</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 模式">
|
||||
对于 `openai/*` 上的 GPT-5 系列运行，OpenClaw 可以使用更严格的嵌入式执行契约：
|
||||
<Accordion title="严格智能体 GPT 模式">
|
||||
对于运行在 `openai/*` 上的 GPT-5 系列，OpenClaw 可以使用更严格的嵌入式执行契约：
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -732,32 +726,32 @@ OpenClaw 的隐藏归因请求头——请参阅 [高级配置](#advanced-config
|
||||
```
|
||||
|
||||
使用 `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/*`、Azure OpenAI）：
|
||||
**原生接入方式**（`openai/*`、Azure OpenAI）：
|
||||
- 仅对支持 OpenAI `none` effort 的模型保留 `reasoning: { effort: "none" }`
|
||||
- 对会拒绝 `reasoning.effort: "none"` 的模型或代理省略禁用的 reasoning
|
||||
- 对拒绝 `reasoning.effort: "none"` 的模型或代理省略禁用推理设置
|
||||
- 默认将工具 schema 设为严格模式
|
||||
- 仅在已验证的原生主机上附加隐藏归因请求头
|
||||
- 保留 OpenAI 专用的请求整形（`service_tier`、`store`、reasoning 兼容性、prompt-cache 提示）
|
||||
- 仅在已验证的原生主机上附加隐藏 attribution 请求头
|
||||
- 保留 OpenAI 专用的请求格式处理（`service_tier`、`store`、reasoning 兼容性、prompt-cache 提示）
|
||||
|
||||
**代理 / 兼容路由：**
|
||||
**代理 / 兼容接入方式：**
|
||||
- 使用更宽松的兼容行为
|
||||
- 不强制严格工具 schema 或原生专用请求头
|
||||
- 不强制使用严格工具 schema 或原生专用请求头
|
||||
|
||||
Azure OpenAI 使用原生传输和兼容行为，但不会接收隐藏归因请求头。
|
||||
Azure OpenAI 使用原生传输和兼容行为，但不会接收隐藏 attribution 请求头。
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@ -774,7 +768,7 @@ OpenClaw 的隐藏归因请求头——请参阅 [高级配置](#advanced-config
|
||||
<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>
|
||||
|
||||
@ -1,45 +1,45 @@
|
||||
---
|
||||
read_when:
|
||||
- 你想通过浏览器操作 Gateway 网关
|
||||
- 你想在不使用 SSH 隧道的情况下获得 Tailnet 访问能力
|
||||
summary: Gateway 网关的基于浏览器的控制界面（聊天、节点、配置）
|
||||
- 你想在不使用 SSH 隧道的情况下获得 Tailnet 访问权限
|
||||
summary: 用于 Gateway 网关的基于浏览器的控制界面（聊天、节点、配置）
|
||||
title: 控制界面
|
||||
x-i18n:
|
||||
generated_at: "2026-04-24T01:39:17Z"
|
||||
generated_at: "2026-04-24T02:37:00Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 931a87479844fc5c06f2c373d3e7447c140bf6d17a5614197209e7a5f3f896bd
|
||||
source_hash: edf6beb9c485720b6811d9d348bbb4752cf6aae929a9fbc62fc8c4770e762490
|
||||
source_path: web/control-ui.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
控制界面是一个由 Gateway 网关提供服务的小型 **Vite + Lit** 单页应用：
|
||||
Control UI 是一个由 Gateway 网关提供服务的小型 **Vite + Lit** 单页应用：
|
||||
|
||||
- 默认：`http://<host>:18789/`
|
||||
- 可选前缀：设置 `gateway.controlUi.basePath`（例如 `/openclaw`）
|
||||
|
||||
它会在同一端口上**直接连接到 Gateway 网关 WebSocket**。
|
||||
它会在同一端口上**直接连接到 Gateway WebSocket**。
|
||||
|
||||
## 快速打开（本地）
|
||||
|
||||
如果 Gateway 网关运行在同一台计算机上，请打开：
|
||||
如果 Gateway 网关运行在同一台电脑上，请打开：
|
||||
|
||||
- [http://127.0.0.1:18789/](http://127.0.0.1:18789/)（或 [http://localhost:18789/](http://localhost:18789/)）
|
||||
|
||||
如果页面加载失败，请先启动 Gateway 网关：`openclaw gateway`。
|
||||
|
||||
身份验证会在 WebSocket 握手期间通过以下方式提供：
|
||||
认证会在 WebSocket 握手期间通过以下方式提供：
|
||||
|
||||
- `connect.params.auth.token`
|
||||
- `connect.params.auth.password`
|
||||
- 当 `gateway.auth.allowTailscale: true` 时使用 Tailscale Serve 身份标头
|
||||
- 当 `gateway.auth.mode: "trusted-proxy"` 时使用受信任代理身份标头
|
||||
- 当 `gateway.auth.mode: "trusted-proxy"` 时使用 trusted-proxy 身份标头
|
||||
|
||||
仪表板设置面板会为当前浏览器标签页会话保存一个 token 和所选的 Gateway 网关 URL；密码不会被持久化保存。新手引导通常会在首次连接时为共享密钥认证生成一个 gateway token，但当 `gateway.auth.mode` 为 `"password"` 时，密码认证也可以正常使用。
|
||||
仪表板设置面板会为当前浏览器标签页会话保存一个 token 和所选的 gateway URL；不会持久化保存密码。新手引导通常会在首次连接时为共享密钥认证生成一个 gateway token，但当 `gateway.auth.mode` 为 `"password"` 时，密码认证也可使用。
|
||||
|
||||
## 设备配对（首次连接）
|
||||
|
||||
当你从新的浏览器或设备连接到控制界面时，Gateway 网关会要求进行**一次性配对批准**——即使你位于同一个 Tailnet 且设置了 `gateway.auth.allowTailscale: true` 也是如此。这是一项安全措施，用于防止未授权访问。
|
||||
当你从新的浏览器或设备连接到 Control UI 时，Gateway 网关会要求进行**一次性配对批准**——即使你位于同一个 Tailnet 中，且设置了 `gateway.auth.allowTailscale: true` 也是如此。这是一项安全措施，用于防止未经授权的访问。
|
||||
|
||||
**你会看到：** “disconnected (1008): pairing required”
|
||||
|
||||
@ -53,96 +53,98 @@ openclaw devices list
|
||||
openclaw devices approve <requestId>
|
||||
```
|
||||
|
||||
如果浏览器在认证详情发生变化后重试配对（角色/作用域/公钥），之前的待处理请求会被替代，并创建新的 `requestId`。请在批准前重新运行 `openclaw devices list`。
|
||||
如果浏览器使用变更后的认证详情（角色 / scopes / 公钥）重试配对，之前的待处理请求会被替代，并创建新的 `requestId`。批准前请重新运行 `openclaw devices list`。
|
||||
|
||||
如果浏览器已经完成配对，而你将其访问权限从只读改为写入/管理员权限，这会被视为批准升级，而不是静默重连。OpenClaw 会保持旧批准仍然有效，阻止更高权限的重连，并要求你显式批准新的作用域集合。
|
||||
如果浏览器已经完成配对，而你将其权限从只读更改为写入 / 管理员访问，这会被视为批准升级，而不是静默重连。OpenClaw 会保留旧批准的有效状态，阻止更宽权限的重连，并要求你显式批准新的权限范围集合。
|
||||
|
||||
一旦获得批准，该设备就会被记住，除非你使用 `openclaw devices revoke --device <id> --role <role>` 撤销它，否则无需再次批准。有关 token 轮换和撤销，请参阅 [Devices CLI](/zh-CN/cli/devices)。
|
||||
批准后，设备会被记住，除非你使用 `openclaw devices revoke --device <id> --role <role>` 撤销它，否则无需再次批准。有关 token 轮换和撤销，请参阅 [Devices CLI](/zh-CN/cli/devices)。
|
||||
|
||||
**注意：**
|
||||
|
||||
- 直接的本地 local loopback 浏览器连接（`127.0.0.1` / `localhost`）会自动批准。
|
||||
- Tailnet 和局域网浏览器连接仍然需要显式批准，即使它们来自同一台机器。
|
||||
- 直接的本地 local loopback 浏览器连接（`127.0.0.1` / `localhost`）会被自动批准。
|
||||
- Tailnet 和 LAN 浏览器连接仍然需要显式批准，即使它们来自同一台机器。
|
||||
- 每个浏览器配置文件都会生成唯一的设备 ID，因此切换浏览器或清除浏览器数据都需要重新配对。
|
||||
|
||||
## 个人身份（浏览器本地）
|
||||
|
||||
控制界面支持按浏览器分别设置个人身份（显示名称和头像），并将其附加到发出的消息上，以便在共享会话中进行归属标识。它存储在浏览器存储中，作用域限定为当前浏览器配置文件，不会同步到其他设备，也不会在服务端持久化保存，除非是你实际发送的消息上附带的常规转录作者元数据。清除站点数据或切换浏览器会将其重置为空。
|
||||
Control UI 支持按浏览器分别设置个人身份（显示名称和头像），该身份会附加到发出的消息上，用于共享会话中的归属标识。它保存在浏览器存储中，仅限当前浏览器配置文件使用，不会同步到其他设备，也不会在服务端持久化保存，除了你实际发送的消息中正常的对话记录作者元数据。清除站点数据或切换浏览器会将其重置为空。
|
||||
|
||||
## 运行时配置端点
|
||||
|
||||
控制界面会从 `/**__openclaw**/control-ui-config.json` 获取其运行时设置。该端点受与其余 HTTP 表面相同的 gateway 认证保护：未认证的浏览器无法获取它，成功获取需要已有效的 gateway token/密码、Tailscale Serve 身份，或受信任代理身份之一。
|
||||
Control UI 会从 `\/__openclaw/control-ui-config.json` 获取其运行时设置。该端点与其他 HTTP 接口一样受相同的 gateway 认证保护：未认证的浏览器无法获取它，成功获取需要已有效的 gateway token / password、Tailscale Serve 身份，或 trusted-proxy 身份。
|
||||
|
||||
## 语言支持
|
||||
|
||||
控制界面可以在首次加载时根据你的浏览器区域设置自动本地化。若要稍后覆盖，请打开 **概览 -> Gateway Access -> 语言**。区域设置选择器位于 Gateway Access 卡片中，而不是在外观设置下。
|
||||
Control UI 可以在首次加载时根据你的浏览器区域设置进行本地化。若要稍后覆盖，请打开 **Overview -> Gateway Access -> Language**。区域设置选择器位于 Gateway Access 卡片中，而不在 Appearance 下。
|
||||
|
||||
- 支持的区域设置：`en`, `zh-CN`, `zh-TW`, `pt-BR`, `de`, `es`, `ja-JP`, `ko`, `fr`, `tr`, `uk`, `id`, `pl`, `th`
|
||||
- 非英语翻译会在浏览器中按需懒加载。
|
||||
- 所选区域设置会保存在浏览器存储中，并在未来访问时复用。
|
||||
- 缺失的翻译键会回退到英语。
|
||||
- 非英文翻译会在浏览器中按需懒加载。
|
||||
- 所选区域设置会保存在浏览器存储中，并在之后访问时重复使用。
|
||||
- 缺失的翻译键会回退到英文。
|
||||
|
||||
## 它目前可以做什么
|
||||
## 它目前能做什么
|
||||
|
||||
- 通过 Gateway 网关 WS 与模型聊天（`chat.history`, `chat.send`, `chat.abort`, `chat.inject`）
|
||||
- 在聊天中流式显示工具调用 + 实时工具输出卡片（智能体事件）
|
||||
- 渠道：内置渠道以及内置/外部插件渠道的状态、二维码登录和按渠道配置（`channels.status`, `web.login.*`, `config.patch`）
|
||||
- 通过 Gateway WS 与模型聊天（`chat.history`, `chat.send`, `chat.abort`, `chat.inject`）
|
||||
- 通过 WebRTC 直接从浏览器连接到 OpenAI Realtime。Gateway 网关使用 `talk.realtime.session` 签发短期有效的 Realtime 客户端密钥；浏览器将麦克风音频直接发送给 OpenAI，并通过 `chat.send` 将 `openclaw_agent_consult` 工具调用中继回更大、已配置的 OpenClaw 模型。
|
||||
- 在聊天中流式显示工具调用和实时工具输出卡片（智能体事件）
|
||||
- 渠道：内置渠道以及内置 / 外部插件渠道的状态、QR 登录和按渠道配置（`channels.status`, `web.login.*`, `config.patch`）
|
||||
- 实例：在线状态列表 + 刷新（`system-presence`）
|
||||
- 会话：列表 + 按会话覆盖模型/思考/快速/详细/追踪/推理设置（`sessions.list`, `sessions.patch`）
|
||||
- Dreams：Dreaming 状态、启用/禁用开关以及 Dream Diary 阅读器（`doctor.memory.status`, `doctor.memory.dreamDiary`, `config.patch`）
|
||||
- Cron 作业：列出/添加/编辑/运行/启用/禁用 + 运行历史（`cron.*`）
|
||||
- Skills：状态、启用/禁用、安装、API 密钥更新（`skills.*`）
|
||||
- 会话：列表 + 按会话设置模型 / thinking / fast / verbose / trace / reasoning 覆盖项（`sessions.list`, `sessions.patch`）
|
||||
- Dreams：Dreaming 状态、启用 / 禁用切换，以及 Dream Diary 阅读器（`doctor.memory.status`, `doctor.memory.dreamDiary`, `config.patch`）
|
||||
- Cron 作业：列出 / 添加 / 编辑 / 运行 / 启用 / 禁用 + 运行历史（`cron.*`）
|
||||
- Skills：状态、启用 / 禁用、安装、API key 更新（`skills.*`）
|
||||
- 节点：列表 + 能力上限（`node.list`）
|
||||
- Exec 批准：编辑 gateway 或节点允许列表 + 针对 `exec host=gateway/node` 的询问策略（`exec.approvals.*`）
|
||||
- 配置：查看/编辑 `~/.openclaw/openclaw.json`（`config.get`, `config.set`）
|
||||
- 配置：应用并在验证后重启（`config.apply`），并唤醒最近活跃的会话
|
||||
- 配置写入包含 base-hash 防护，以防覆盖并发编辑
|
||||
- 配置写入（`config.set`/`config.apply`/`config.patch`）还会对已提交配置负载中的 SecretRef 执行活动解析预检；未解析的活动已提交引用会在写入前被拒绝
|
||||
- 配置 schema + 表单渲染（`config.schema` / `config.schema.lookup`，包括字段 `title` / `description`、匹配的 UI 提示、直接子项摘要、嵌套对象/通配符/数组/组合节点上的文档元数据，以及可用时的插件 + 渠道 schema）；仅当快照能够安全进行原始往返时，才提供原始 JSON 编辑器
|
||||
- 如果某个快照无法安全地进行原始往返，控制界面会强制使用表单模式，并为该快照禁用原始模式
|
||||
- 原始 JSON 编辑器中的“重置为已保存”会保留原始编写形态（格式、注释、`$include` 布局），而不是重新渲染扁平化快照，因此在快照可以安全往返时，外部编辑在重置后仍可保留
|
||||
- 结构化 SecretRef 对象值会在表单文本输入中以只读方式渲染，以防意外将对象损坏为字符串
|
||||
- 调试：状态/健康状况/模型快照 + 事件日志 + 手动 RPC 调用（`status`, `health`, `models.list`）
|
||||
- 日志：Gateway 网关文件日志的实时 tail，支持过滤/导出（`logs.tail`）
|
||||
- 更新：运行 package/git 更新 + 重启（`update.run`），并附带重启报告
|
||||
- Exec 批准：编辑 gateway 或节点 allowlists + 为 `exec host=gateway/node` 询问策略（`exec.approvals.*`）
|
||||
- 配置：查看 / 编辑 `~/.openclaw/openclaw.json`（`config.get`, `config.set`）
|
||||
- 配置：带验证地应用并重启（`config.apply`），并唤醒最近活跃的会话
|
||||
- 配置写入包含 base-hash 保护，以防覆盖并发编辑
|
||||
- 配置写入（`config.set` / `config.apply` / `config.patch`）还会预检已提交配置负载中引用的活动 SecretRef 解析；未解析的活动已提交引用会在写入前被拒绝
|
||||
- 配置 schema + 表单渲染（`config.schema` / `config.schema.lookup`，包括字段 `title` / `description`、匹配的 UI 提示、直接子项摘要、嵌套对象 / wildcard / 数组 / 组合节点上的文档元数据，以及在可用时的插件 + 渠道 schema）；仅当快照具备安全的原始往返能力时，才提供原始 JSON 编辑器
|
||||
- 如果某个快照无法安全地进行原始文本往返，Control UI 会强制使用表单模式，并为该快照禁用原始模式
|
||||
- 原始 JSON 编辑器中的“Reset to saved”会保留原始编写的结构（格式、注释、`$include` 布局），而不是重新渲染扁平化后的快照，因此在快照可安全往返时，外部编辑在重置后仍会保留
|
||||
- 结构化 SecretRef 对象值会在表单文本输入中以只读方式渲染，以防止意外将对象破坏性地转换为字符串
|
||||
- 调试：状态 / 健康 / 模型快照 + 事件日志 + 手动 RPC 调用（`status`, `health`, `models.list`）
|
||||
- 日志：实时 tail gateway 文件日志，并支持过滤 / 导出（`logs.tail`）
|
||||
- 更新：运行包 / git 更新并重启（`update.run`），附带重启报告
|
||||
|
||||
Cron 作业面板说明：
|
||||
|
||||
- 对于隔离作业，投递默认使用公告摘要。如果你希望仅内部运行，可以切换为 none。
|
||||
- 选择 announce 后会显示渠道/目标字段。
|
||||
- Webhook 模式使用 `delivery.mode = "webhook"`，并将 `delivery.to` 设为有效的 HTTP(S) webhook URL。
|
||||
- 对于主会话作业，可使用 webhook 和 none 投递模式。
|
||||
- 高级编辑控件包括运行后删除、清除智能体覆盖、cron 精确/错峰选项、智能体模型/思考覆盖，以及尽力投递切换。
|
||||
- 表单验证为内联字段级错误；在修复前，无效值会禁用保存按钮。
|
||||
- 设置 `cron.webhookToken` 可发送专用 bearer token；若省略，webhook 将在不带认证标头的情况下发送。
|
||||
- 已弃用的回退方式：存储的旧版作业若带有 `notify: true`，在迁移前仍可使用 `cron.webhook`。
|
||||
- 对于隔离作业，默认投递方式为公告摘要。如果你希望仅限内部运行，可以切换为 none。
|
||||
- 选择 announce 时会显示 channel / target 字段。
|
||||
- Webhook 模式使用 `delivery.mode = "webhook"`，并将 `delivery.to` 设置为有效的 HTTP(S) webhook URL。
|
||||
- 对于主会话作业，可用的投递模式包括 webhook 和 none。
|
||||
- 高级编辑控件包括运行后删除、清除智能体覆盖项、cron 精确 / 错开选项、智能体 model / thinking 覆盖项，以及尽力投递切换项。
|
||||
- 表单验证为内联验证，并带有字段级错误；在修复之前，无效值会禁用保存按钮。
|
||||
- 设置 `cron.webhookToken` 可发送专用 bearer token；若省略，则 webhook 发送时不带 auth 标头。
|
||||
- 已弃用的回退：带有 `notify: true` 的旧版已存储作业在迁移前仍可使用 `cron.webhook`。
|
||||
|
||||
## 聊天行为
|
||||
|
||||
- `chat.send` 是**非阻塞**的：它会立即确认并返回 `{ runId, status: "started" }`，响应通过 `chat` 事件流式传输。
|
||||
- 使用相同的 `idempotencyKey` 再次发送时，运行中会返回 `{ status: "in_flight" }`，完成后会返回 `{ status: "ok" }`。
|
||||
- 出于 UI 安全考虑，`chat.history` 响应有大小限制。当转录条目过大时，Gateway 网关可能会截断长文本字段、省略大型元数据块，并用占位符替换超大消息（`[chat.history omitted: message too large]`）。
|
||||
- 助手/生成的图片会以托管媒体引用的形式持久化，并通过经认证的 Gateway 网关媒体 URL 返回，因此重新加载不依赖于原始 base64 图片负载仍保留在聊天历史响应中。
|
||||
- `chat.history` 还会从可见的助手文本中去除仅用于显示的内联指令标签（例如 `[[reply_to_*]]` 和 `[[audio_as_voice]]`）、纯文本工具调用 XML 负载（包括 `<tool_call>...</tool_call>`、`<function_call>...</function_call>`、`<tool_calls>...</tool_calls>`、`<function_calls>...</function_calls>` 以及被截断的工具调用块），以及泄露的 ASCII/全角模型控制 token；并省略那些其全部可见文本仅为精确静默 token `NO_REPLY` / `no_reply` 的助手条目。
|
||||
- `chat.inject` 会向会话转录追加一条助手备注，并广播一个 `chat` 事件用于仅 UI 更新（不运行智能体，不向渠道投递）。
|
||||
- 聊天标题栏中的模型和思考选择器会立即通过 `sessions.patch` 修改当前活跃会话；它们是持久化的会话覆盖，而不是仅单轮发送选项。
|
||||
- `chat.send` 是**非阻塞**的：它会立即确认并返回 `{ runId, status: "started" }`，随后响应通过 `chat` 事件流式传输。
|
||||
- 使用相同的 `idempotencyKey` 重新发送时，如果仍在运行中会返回 `{ status: "in_flight" }`，完成后返回 `{ status: "ok" }`。
|
||||
- 出于 UI 安全考虑，`chat.history` 响应有大小限制。当对话记录条目过大时，Gateway 网关可能会截断长文本字段、省略较重的元数据块，并用占位符替换超大消息（`[chat.history omitted: message too large]`）。
|
||||
- 助手 / 生成的图像会作为受管媒体引用持久化，并通过已认证的 Gateway 媒体 URL 返回，因此重新加载不依赖聊天记录响应中原始 base64 图像负载继续存在。
|
||||
- `chat.history` 还会从可见的助手文本中移除仅用于显示的内联指令标签（例如 `[[reply_to_*]]` 和 `[[audio_as_voice]]`）、纯文本工具调用 XML 负载（包括 `<tool_call>...</tool_call>`、`<function_call>...</function_call>`、`<tool_calls>...</tool_calls>`、`<function_calls>...</function_calls>` 以及被截断的工具调用块）、以及泄露的 ASCII / 全角模型控制 token，并省略那些整个可见文本仅为精确静默 token `NO_REPLY` / `no_reply` 的助手条目。
|
||||
- `chat.inject` 会向会话对话记录追加一条助手备注，并广播一个 `chat` 事件用于仅 UI 更新（不运行智能体，不投递到渠道）。
|
||||
- 聊天头部中的 model 和 thinking 选择器会立即通过 `sessions.patch` 修补当前活动会话；它们是持久的会话覆盖项，而不是仅单轮发送选项。
|
||||
- 通话模式使用已注册的实时语音提供商。请使用 `talk.provider: "openai"` 加上 `talk.providers.openai.apiKey` 配置 OpenAI，或者复用 Voice Call 实时提供商配置。浏览器永远不会收到标准 OpenAI API key；它只会收到临时 Realtime 客户端密钥。
|
||||
- 停止：
|
||||
- 点击 **停止**（调用 `chat.abort`）
|
||||
- 当某次运行处于活动状态时，普通后续消息会排队。点击已排队消息上的 **Steer**，可将该后续内容注入正在运行的轮次。
|
||||
- 点击 **Stop**（调用 `chat.abort`）
|
||||
- 当某次运行处于活跃状态时，普通后续消息会排队。点击已排队消息上的 **Steer** 可将该后续消息注入当前运行轮次。
|
||||
- 输入 `/stop`（或独立的中止短语，如 `stop`、`stop action`、`stop run`、`stop openclaw`、`please stop`）可进行带外中止
|
||||
- `chat.abort` 支持 `{ sessionKey }`（无需 `runId`）以中止该会话的所有活动运行
|
||||
- 中止后的部分内容保留：
|
||||
- `chat.abort` 支持 `{ sessionKey }`（无需 `runId`）来中止该会话的所有活跃运行
|
||||
- 中止后的部分保留：
|
||||
- 当某次运行被中止时，部分助手文本仍可能显示在 UI 中
|
||||
- 当存在缓冲输出时，Gateway 网关会将中止时的部分助手文本持久化到转录历史中
|
||||
- 持久化条目会包含中止元数据，以便转录消费者区分中止的部分内容与正常完成输出
|
||||
- 当存在缓冲输出时，Gateway 网关会将已中止的部分助手文本持久化到对话记录历史中
|
||||
- 持久化条目包含中止元数据，因此对话记录消费者可以将中止的部分内容与正常完成输出区分开来
|
||||
|
||||
## 托管嵌入
|
||||
|
||||
助手消息可以通过 `[embed ...]` 简码以内联方式渲染托管网页内容。iframe 沙箱策略由 `gateway.controlUi.embedSandbox` 控制：
|
||||
助手消息可以通过 `[embed ...]` 短代码内联渲染托管的网页内容。iframe 沙箱策略由 `gateway.controlUi.embedSandbox` 控制：
|
||||
|
||||
- `strict`：禁用托管嵌入中的脚本执行
|
||||
- `scripts`：允许交互式嵌入，同时保持源隔离；这是默认值，通常足以支持自包含的浏览器游戏/小部件
|
||||
- `trusted`：在 `allow-scripts` 之上再添加 `allow-same-origin`，用于有意需要更强权限的同站文档
|
||||
- `scripts`：允许交互式嵌入，同时保持源隔离；这是默认值，通常足以支持自包含的浏览器游戏 / 小部件
|
||||
- `trusted`：在 `allow-scripts` 之外再添加 `allow-same-origin`，用于有意需要更高权限的同站文档
|
||||
|
||||
示例：
|
||||
|
||||
@ -158,13 +160,13 @@ Cron 作业面板说明：
|
||||
|
||||
仅当嵌入文档确实需要同源行为时才使用 `trusted`。对于大多数由智能体生成的游戏和交互式画布，`scripts` 是更安全的选择。
|
||||
|
||||
默认情况下，绝对外部 `http(s)` 嵌入 URL 仍会被阻止。如果你确实希望 `[embed url="https://..."]` 加载第三方页面，请设置 `gateway.controlUi.allowExternalEmbedUrls: true`。
|
||||
绝对外部 `http(s)` 嵌入 URL 默认仍会被阻止。如果你确实希望 `[embed url="https://..."]` 加载第三方页面，请设置 `gateway.controlUi.allowExternalEmbedUrls: true`。
|
||||
|
||||
## Tailnet 访问（推荐）
|
||||
|
||||
### 集成式 Tailscale Serve（首选）
|
||||
### 集成的 Tailscale Serve（首选）
|
||||
|
||||
让 Gateway 网关保持在 loopback 上，并让 Tailscale Serve 通过 HTTPS 代理它：
|
||||
让 Gateway 网关保持在 loopback 上，并让 Tailscale Serve 使用 HTTPS 为其提供代理：
|
||||
|
||||
```bash
|
||||
openclaw gateway --tailscale serve
|
||||
@ -174,16 +176,12 @@ openclaw gateway --tailscale serve
|
||||
|
||||
- `https://<magicdns>/`（或你配置的 `gateway.controlUi.basePath`）
|
||||
|
||||
默认情况下，当 `gateway.auth.allowTailscale` 为 `true` 时，控制界面 / WebSocket Serve 请求可以通过 Tailscale 身份标头（`tailscale-user-login`）进行认证。OpenClaw 会通过 `tailscale whois` 解析 `x-forwarded-for` 地址并将其与标头匹配来验证身份，并且仅当请求命中 loopback 且带有 Tailscale 的 `x-forwarded-*` 标头时才接受这些请求。如果你希望即使对于 Serve 流量也要求显式共享密钥凭证，请设置 `gateway.auth.allowTailscale: false`。然后使用 `gateway.auth.mode: "token"` 或 `"password"`。
|
||||
对于该异步 Serve 身份路径，来自相同客户端 IP 和认证作用域的失败认证尝试会在写入速率限制之前串行化处理。因此，同一浏览器的并发错误重试在第二个请求上可能会显示 `retry later`，而不是两个普通不匹配并行竞争。
|
||||
无 token 的 Serve 认证假定 gateway 主机是可信的。如果该主机上可能运行不受信任的本地代码，请要求使用 token/密码认证。
|
||||
默认情况下，当 `gateway.auth.allowTailscale` 为 `true` 时，Control UI / WebSocket Serve 请求可以通过 Tailscale 身份标头（`tailscale-user-login`）进行认证。OpenClaw 会通过 `tailscale whois` 解析 `x-forwarded-for` 地址并将其与该标头匹配来验证身份，并且仅当请求通过 Tailscale 的 `x-forwarded-*` 标头命中 loopback 时才接受这些标头。如果你希望即使对于 Serve 流量也要求显式共享密钥凭证，请设置 `gateway.auth.allowTailscale: false`。然后使用 `gateway.auth.mode: "token"` 或 `"password"``。
|
||||
对于该异步 Serve 身份路径，来自同一客户端 IP 和认证范围的失败认证尝试会在写入速率限制之前被串行化。因此，同一浏览器发起的并发错误重试在第二个请求上可能会显示 `retry later`，而不是两个普通不匹配并行竞争。
|
||||
无 token 的 Serve 认证假定 gateway 主机是可信的。如果该主机上可能运行不受信任的本地代码，请要求使用 token / password 认证。
|
||||
|
||||
### 绑定到 tailnet + token
|
||||
|
||||
```bash
|
||||
openclaw gateway --bind tailnet --token "$(openssl rand -hex 32)"
|
||||
```
|
||||
|
||||
__OC_I18N_900003__
|
||||
然后打开：
|
||||
|
||||
- `http://<tailscale-ip>:18789/`（或你配置的 `gateway.controlUi.basePath`）
|
||||
@ -192,133 +190,92 @@ openclaw gateway --bind tailnet --token "$(openssl rand -hex 32)"
|
||||
|
||||
## 不安全的 HTTP
|
||||
|
||||
如果你通过纯 HTTP 打开仪表板（`http://<lan-ip>` 或 `http://<tailscale-ip>`），浏览器会运行在**非安全上下文**中并阻止 WebCrypto。默认情况下，OpenClaw **会阻止**没有设备身份的控制界面连接。
|
||||
如果你通过明文 HTTP 打开仪表板（`http://<lan-ip>` 或 `http://<tailscale-ip>`），浏览器会运行在**非安全上下文**中，并阻止 WebCrypto。默认情况下，OpenClaw 会**阻止**没有设备身份的 Control UI 连接。
|
||||
|
||||
文档化的例外情况：
|
||||
文档说明的例外情况：
|
||||
|
||||
- 使用 `gateway.controlUi.allowInsecureAuth=true` 的仅 localhost 不安全 HTTP 兼容模式
|
||||
- 通过 `gateway.auth.mode: "trusted-proxy"` 成功完成的操作员控制界面认证
|
||||
- 紧急兜底 `gateway.controlUi.dangerouslyDisableDeviceAuth=true`
|
||||
- 仅限 localhost 的不安全 HTTP 兼容模式，使用 `gateway.controlUi.allowInsecureAuth=true`
|
||||
- 通过 `gateway.auth.mode: "trusted-proxy"` 成功进行 operator Control UI 认证
|
||||
- 紧急兜底模式 `gateway.controlUi.dangerouslyDisableDeviceAuth=true`
|
||||
|
||||
**推荐修复方式：** 使用 HTTPS（Tailscale Serve）或在本地打开 UI：
|
||||
**推荐修复方式：** 使用 HTTPS（Tailscale Serve），或在本地打开 UI：
|
||||
|
||||
- `https://<magicdns>/`（Serve）
|
||||
- `http://127.0.0.1:18789/`（在 gateway 主机上）
|
||||
|
||||
**不安全认证开关行为：**
|
||||
__OC_I18N_900004__
|
||||
`allowInsecureAuth` 只是本地兼容性开关：
|
||||
|
||||
```json5
|
||||
{
|
||||
gateway: {
|
||||
controlUi: { allowInsecureAuth: true },
|
||||
bind: "tailnet",
|
||||
auth: { mode: "token", token: "replace-me" },
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
`allowInsecureAuth` 只是一个本地兼容性开关：
|
||||
|
||||
- 它允许 localhost 控制界面会话在非安全 HTTP 上下文中无设备身份继续进行。
|
||||
- 它允许 localhost Control UI 会话在非安全 HTTP 上下文中无设备身份继续进行。
|
||||
- 它不会绕过配对检查。
|
||||
- 它不会放宽远程（非 localhost）设备身份要求。
|
||||
|
||||
**仅限紧急兜底：**
|
||||
__OC_I18N_900005__
|
||||
`dangerouslyDisableDeviceAuth` 会禁用 Control UI 设备身份检查，这是严重的安全降级。紧急使用后请尽快恢复。
|
||||
|
||||
```json5
|
||||
{
|
||||
gateway: {
|
||||
controlUi: { dangerouslyDisableDeviceAuth: true },
|
||||
bind: "tailnet",
|
||||
auth: { mode: "token", token: "replace-me" },
|
||||
},
|
||||
}
|
||||
```
|
||||
trusted-proxy 说明：
|
||||
|
||||
`dangerouslyDisableDeviceAuth` 会禁用控制界面的设备身份检查，这是严重的安全降级。紧急使用后请尽快恢复。
|
||||
- 成功的 trusted-proxy 认证可以允许**operator** Control UI 会话在无设备身份的情况下接入
|
||||
- 这**不**适用于 node-role Control UI 会话
|
||||
- 同主机上的 loopback 反向代理仍然不能满足 trusted-proxy 认证；请参阅 [Trusted Proxy Auth](/gateway/trusted-proxy-auth)
|
||||
|
||||
受信任代理说明：
|
||||
|
||||
- 成功的受信任代理认证可以在没有设备身份的情况下允许**操作员**控制界面会话
|
||||
- 这**不**适用于节点角色的控制界面会话
|
||||
- 同主机 loopback 反向代理仍然不能满足受信任代理认证；请参阅 [Trusted Proxy Auth](/zh-CN/gateway/trusted-proxy-auth)
|
||||
|
||||
有关 HTTPS 设置指导，请参阅 [Tailscale](/zh-CN/gateway/tailscale)。
|
||||
有关 HTTPS 设置指导，请参阅 [Tailscale](/gateway/tailscale)。
|
||||
|
||||
## 内容安全策略
|
||||
|
||||
控制界面采用严格的 `img-src` 策略：只允许**同源**资源和 `data:` URL。远程 `http(s)` 和协议相对图片 URL 会被浏览器拒绝，且不会发起网络请求。
|
||||
Control UI 使用了严格的 `img-src` 策略：只允许**同源**资源和 `data:` URL。远程 `http(s)` 和协议相对图片 URL 会被浏览器拒绝，也不会发起网络请求。
|
||||
|
||||
这在实践中意味着：
|
||||
这在实际中的含义是：
|
||||
|
||||
- 通过相对路径提供的头像和图片（例如 `/avatars/<id>`）仍然可以渲染。
|
||||
- 内联 `data:image/...` URL 仍然可以渲染（对协议内负载很有用）。
|
||||
- 渠道元数据发出的远程头像 URL 会在控制界面的头像辅助函数中被剥离，并替换为内置 logo/徽章，因此被攻陷或恶意的渠道无法强制操作员浏览器发起任意远程图片请求。
|
||||
- 在相对路径下提供的头像和图片（例如 `/avatars/<id>`）仍然可以渲染。
|
||||
- 内联 `data:image/...` URL 仍然可以渲染（适用于协议内负载）。
|
||||
- 由渠道元数据输出的远程头像 URL 会在 Control UI 的头像辅助函数中被剥离，并替换为内置 logo / badge，因此被攻陷或恶意的渠道无法强制 operator 浏览器发起任意远程图片请求。
|
||||
|
||||
你无需做任何更改即可获得此行为——它始终启用且不可配置。
|
||||
你无需做任何改动即可获得此行为——它始终开启，且不可配置。
|
||||
|
||||
## 头像路由认证
|
||||
|
||||
当配置了 gateway 认证时，控制界面的头像端点要求与其余 API 相同的 gateway token：
|
||||
配置了 gateway 认证后，Control UI 头像端点需要与 API 其余部分相同的 gateway token：
|
||||
|
||||
- `GET /avatar/<agentId>` 仅向已认证调用方返回头像图片。`GET /avatar/<agentId>?meta=1` 在相同规则下返回头像元数据。
|
||||
- 对这两个路由的未认证请求都会被拒绝（与相邻的 assistant-media 路由保持一致）。这可以防止头像路由在其他方面受保护的主机上泄露智能体身份。
|
||||
- 控制界面本身在获取头像时会将 gateway token 作为 bearer 标头转发，并使用已认证的 blob URL，因此图片仍可在仪表板中渲染。
|
||||
- 对这两个路由的未认证请求都会被拒绝（与相邻的 assistant-media 路由一致）。这可以防止头像路由在原本受保护的主机上泄露智能体身份。
|
||||
- Control UI 本身在获取头像时会以 bearer 标头转发 gateway token，并使用已认证的 blob URL，因此图片仍可在仪表板中渲染。
|
||||
|
||||
如果你禁用了 gateway 认证（不推荐在共享主机上这样做），头像路由也会变为未认证状态，与其余 gateway 保持一致。
|
||||
如果你禁用了 gateway 认证（不建议在共享主机上这样做），头像路由也会变为无需认证，这与 gateway 的其余部分保持一致。
|
||||
|
||||
## 构建 UI
|
||||
|
||||
Gateway 网关会从 `dist/control-ui` 提供静态文件服务。使用以下命令构建它们：
|
||||
|
||||
```bash
|
||||
pnpm ui:build
|
||||
```
|
||||
|
||||
可选的绝对基础路径（当你希望使用固定资源 URL 时）：
|
||||
|
||||
```bash
|
||||
OPENCLAW_CONTROL_UI_BASE_PATH=/openclaw/ pnpm ui:build
|
||||
```
|
||||
|
||||
Gateway 网关从 `dist/control-ui` 提供静态文件服务。使用以下命令构建：
|
||||
__OC_I18N_900006__
|
||||
可选的绝对 base 路径（当你希望使用固定资源 URL 时）：
|
||||
__OC_I18N_900007__
|
||||
用于本地开发（独立开发服务器）：
|
||||
__OC_I18N_900008__
|
||||
然后将 UI 指向你的 Gateway WS URL（例如 `ws://127.0.0.1:18789`）。
|
||||
|
||||
```bash
|
||||
pnpm ui:dev
|
||||
```
|
||||
## 调试 / 测试：开发服务器 + 远程 Gateway
|
||||
|
||||
然后将 UI 指向你的 Gateway 网关 WS URL（例如 `ws://127.0.0.1:18789`）。
|
||||
|
||||
## 调试/测试：开发服务器 + 远程 Gateway
|
||||
|
||||
控制界面是静态文件；WebSocket 目标是可配置的，并且可以与 HTTP 源不同。当你希望本地使用 Vite 开发服务器，而 Gateway 网关运行在其他地方时，这会很有用。
|
||||
Control UI 是静态文件；WebSocket 目标是可配置的，并且可以不同于 HTTP 源。当你希望本地运行 Vite 开发服务器，而 Gateway 运行在其他地方时，这会非常方便。
|
||||
|
||||
1. 启动 UI 开发服务器：`pnpm ui:dev`
|
||||
2. 打开类似如下的 URL：
|
||||
|
||||
```text
|
||||
http://localhost:5173/?gatewayUrl=ws://<gateway-host>:18789
|
||||
```
|
||||
|
||||
2. 打开如下 URL：
|
||||
__OC_I18N_900009__
|
||||
可选的一次性认证（如果需要）：
|
||||
|
||||
```text
|
||||
http://localhost:5173/?gatewayUrl=wss://<gateway-host>:18789#token=<gateway-token>
|
||||
```
|
||||
|
||||
__OC_I18N_900010__
|
||||
说明：
|
||||
|
||||
- `gatewayUrl` 会在加载后存储到 `localStorage` 中，并从 URL 中移除。
|
||||
- 应尽可能通过 URL 片段（`#token=...`）传递 `token`。片段不会发送到服务器，这样可以避免请求日志和 Referer 泄露。出于兼容性考虑，旧版 `?token=` 查询参数仍会被一次性导入，但仅作为回退方式，并会在引导后立即移除。
|
||||
- `gatewayUrl` 会在加载后存储到 localStorage 中，并从 URL 中移除。
|
||||
- `token` 应尽可能通过 URL 片段（`#token=...`）传递。片段不会发送到服务器，这样可以避免请求日志和 Referer 泄露。为了兼容性，旧版 `?token=` 查询参数仍会被一次性导入，但仅作为后备方案，并会在引导后立即移除。
|
||||
- `password` 仅保存在内存中。
|
||||
- 当设置了 `gatewayUrl` 时，UI 不会回退到配置或环境凭证。
|
||||
- 设置了 `gatewayUrl` 后，UI 不会回退到配置或环境凭证。
|
||||
请显式提供 `token`（或 `password`）。缺少显式凭证会报错。
|
||||
- 当 Gateway 网关位于 TLS 后面时，请使用 `wss://`（Tailscale Serve、HTTPS 代理等）。
|
||||
- `gatewayUrl` 仅在顶层窗口中接受（不能嵌入），以防止点击劫持。
|
||||
- 非 loopback 的控制界面部署必须显式设置 `gateway.controlUi.allowedOrigins`（完整源）。这包括远程开发设置。
|
||||
- 除了受严格控制的本地测试外，不要使用 `gateway.controlUi.allowedOrigins: ["*"]`。
|
||||
这意味着允许任意浏览器源，而不是“匹配我正在使用的任意主机”。
|
||||
- `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` 会启用 Host 标头源回退模式，但这是危险的安全模式。
|
||||
- 当 Gateway 位于 TLS 后面时（Tailscale Serve、HTTPS 代理等），请使用 `wss://`。
|
||||
- `gatewayUrl` 仅在顶层窗口中接受（不可嵌入），以防止点击劫持。
|
||||
- 非 loopback 的 Control UI 部署必须显式设置 `gateway.controlUi.allowedOrigins`（完整 origin）。这也包括远程开发设置。
|
||||
- 除非是严格受控的本地测试，否则不要使用 `gateway.controlUi.allowedOrigins: ["*"]`。它表示允许任意浏览器 origin，而不是“匹配我当前使用的任意主机”。
|
||||
- `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` 会启用 Host 标头 origin 回退模式，但这是危险的安全模式。
|
||||
|
||||
示例：
|
||||
|
||||
@ -332,7 +289,7 @@ http://localhost:5173/?gatewayUrl=wss://<gateway-host>:18789#token=<gateway-toke
|
||||
}
|
||||
```
|
||||
|
||||
远程访问设置详情： [远程访问](/zh-CN/gateway/remote)。
|
||||
远程访问设置详情：[Remote access](/zh-CN/gateway/remote)。
|
||||
|
||||
## 相关内容
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user