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-24 02:29:00 +00:00
parent a31ee95795
commit a3dcb8d5a3
3 changed files with 974 additions and 992 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1447
docs/zh-CN/gateway/configuration-reference.md
View File

File diff suppressed because it is too large Load Diff

195
docs/zh-CN/plugins/sdk-subpaths.md
View File

@ -1,23 +1,23 @@
---
read_when:
- 为插件导入选择合适的 plugin-sdk 子路径
- 审查 bundled-plugin 子路径和辅助接口
summary: 插件 SDK 子路径目录：按领域分组说明各导入位于何处
- 审查 bundled-plugin 子路径和辅助接口 surface
summary: 插件 SDK 子路径目录：按领域分组说明各导入路径的位置
title: 插件 SDK 子路径
x-i18n:
generated_at: "2026-04-24T01:32:01Z"
generated_at: "2026-04-24T02:20:28Z"
model: gpt-5.4
provider: openai
source_hash: 79f44344d9a584380347d0ed0c00cff6652556e5352d2c6143cf6fec092b809e
source_hash: 592cd599c9026eb584773cb7991dd75796f58cd62cd3a85d32e5b106440f7c3e
source_path: plugins/sdk-subpaths.md
workflow: 15
---
plugin SDK 通过 `openclaw/plugin-sdk/` 下的一组精简子路径对外暴露。
本页按用途对常用子路径进行归类整理。生成的完整列表包含 200 多个子路径，位于 `scripts/lib/plugin-sdk-entrypoints.json`；
其中也会出现为 bundled-plugin 预留的辅助子路径，但除非某个文档页面明确将其作为公开能力介绍，否则它们都属于实现细节。
plugin SDK 通过 `openclaw/plugin-sdk/` 下的一组精细子路径公开。
本页按用途分组，汇总常用的子路径。完整的 200+ 子路径生成列表位于 `scripts/lib/plugin-sdk-entrypoints.json`；
其中也包含保留的 bundled-plugin 辅助子路径，但除非某个文档页面明确将其作为公开能力介绍，否则它们都属于实现细节。
关于插件编写指南，请参阅 [插件 SDK 概览](/zh-CN/plugins/sdk-overview)。
关于插件编写指南，参见 [插件 SDK 概览](/zh-CN/plugins/sdk-overview)。
## 插件入口
@ -32,54 +32,54 @@ x-i18n:
<Accordion title="渠道子路径">
| 子路径 | 关键导出 |
| --- | --- |
| `plugin-sdk/channel-core` | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` |
| `plugin-sdk/channel-core` | `defineChannelPluginEntry`、`defineSetupPluginEntry`、`createChatChannelPlugin`、`createChannelPluginBase` |
| `plugin-sdk/config-schema` | 根 `openclaw.json` Zod schema 导出（`OpenClawSchema`） |
| `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`，以及 `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` |
| `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface`、`createOptionalChannelSetupAdapter`、`createOptionalChannelSetupWizard`，以及 `DEFAULT_ACCOUNT_ID`、`createTopLevelChannelDmPolicy`、`setSetupChannelEnabled`、`splitSetupEntries` |
| `plugin-sdk/setup` | 共享的设置向导辅助工具、allowlist 提示、设置状态构建器 |
| `plugin-sdk/setup-runtime` | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` |
| `plugin-sdk/setup-runtime` | `createPatchedAccountSetupAdapter`、`createEnvPatchedAccountSetupAdapter`、`createSetupInputPresenceValidator`、`noteChannelLookupFailure`、`noteChannelLookupSummary`、`promptResolvedAllowFrom`、`splitSetupEntries`、`createAllowlistSetupWizardProxy`、`createDelegatedSetupWizardProxy` |
| `plugin-sdk/setup-adapter-runtime` | `createEnvPatchedAccountSetupAdapter` |
| `plugin-sdk/setup-tools` | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` |
| `plugin-sdk/account-core` | 多账户配置/操作门控辅助工具、默认账户回退辅助工具 |
| `plugin-sdk/setup-tools` | `formatCliCommand`、`detectBinary`、`extractArchive`、`resolveBrewExecutable`、`formatDocsLink`、`CONFIG_DIR` |
| `plugin-sdk/account-core` | 多账户配置/操作门控辅助工具，以及默认账户回退辅助工具 |
| `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`、account-id 规范化辅助工具 |
| `plugin-sdk/account-resolution` | 账户查找 + 默认回退辅助工具 |
| `plugin-sdk/account-helpers` | 精简的账户列表/账户操作辅助工具 |
| `plugin-sdk/account-resolution` | 账户查找 + 默认值回退辅助工具 |
| `plugin-sdk/account-helpers` | 精细的账户列表/账户操作辅助工具 |
| `plugin-sdk/channel-pairing` | `createChannelPairingController` |
| `plugin-sdk/channel-reply-pipeline` | `createChannelReplyPipeline` |
| `plugin-sdk/channel-config-helpers` | `createHybridChannelConfigAdapter` |
| `plugin-sdk/channel-config-schema` | 渠道配置 schema 类型 |
| `plugin-sdk/telegram-command-config` | Telegram 自定义命令规范化/校验辅助工具，带 bundled-contract 回退 |
| `plugin-sdk/command-gating` | 精简的命令授权门控辅助工具 |
| `plugin-sdk/telegram-command-config` | Telegram 自定义命令规范化/校验辅助工具，并带有 bundled-contract 回退 |
| `plugin-sdk/command-gating` | 精细的命令授权门控辅助工具 |
| `plugin-sdk/channel-policy` | `resolveChannelGroupRequireMention` |
| `plugin-sdk/channel-lifecycle` | `createAccountStatusSink`、草稿流生命周期/收尾辅助工具 |
| `plugin-sdk/inbound-envelope` | 共享的入站路由 + envelope 构建器辅助工具 |
| `plugin-sdk/channel-lifecycle` | `createAccountStatusSink`、草稿流生命周期/完成辅助工具 |
| `plugin-sdk/inbound-envelope` | 共享的入站路由 + envelope 构建辅助工具 |
| `plugin-sdk/inbound-reply-dispatch` | 共享的入站记录与分发辅助工具 |
| `plugin-sdk/messaging-targets` | 目标解析/匹配辅助工具 |
| `plugin-sdk/outbound-media` | 共享的出站媒体加载辅助工具 |
| `plugin-sdk/outbound-runtime` | 出站身份、发送委托和负载规划辅助工具 |
| `plugin-sdk/poll-runtime` | 精简的投票规范化辅助工具 |
| `plugin-sdk/thread-bindings-runtime` | 线程绑定生命周期和适配器辅助工具 |
| `plugin-sdk/poll-runtime` | 精细的投票规范化辅助工具 |
| `plugin-sdk/thread-bindings-runtime` | 线程绑定生命周期与适配器辅助工具 |
| `plugin-sdk/agent-media-payload` | 旧版智能体媒体负载构建器 |
| `plugin-sdk/conversation-runtime` | 会话/线程绑定、配对和已配置绑定辅助工具 |
| `plugin-sdk/runtime-config-snapshot` | 运行时配置快照辅助工具 |
| `plugin-sdk/runtime-group-policy` | 运行时群组策略解析辅助工具 |
| `plugin-sdk/channel-status` | 共享的渠道状态快照/摘要辅助工具 |
| `plugin-sdk/channel-config-primitives` | 精简的渠道配置 schema 原语 |
| `plugin-sdk/channel-config-primitives` | 精细的渠道配置 schema 基元 |
| `plugin-sdk/channel-config-writes` | 渠道配置写入授权辅助工具 |
| `plugin-sdk/channel-plugin-common` | 共享的渠道插件前导导出 |
| `plugin-sdk/allowlist-config-edit` | allowlist 配置编辑/读取辅助工具 |
| `plugin-sdk/group-access` | 共享的群组访问决策辅助工具 |
| `plugin-sdk/direct-dm` | 共享的直接私信认证/守卫辅助工具 |
| `plugin-sdk/direct-dm` | 共享的私信认证/保护辅助工具 |
| `plugin-sdk/interactive-runtime` | 语义化消息呈现、投递和旧版交互式回复辅助工具。参见 [消息呈现](/zh-CN/plugins/message-presentation) |
| `plugin-sdk/channel-inbound` | 面向兼容性的 barrel，包含入站去抖、提及匹配、提及策略辅助工具以及 envelope 辅助工具 |
| `plugin-sdk/channel-mention-gating` | 不含更广泛入站运行时接口的精简提及策略辅助工具 |
| `plugin-sdk/channel-location` | 渠道位置上下文和格式化辅助工具 |
| `plugin-sdk/channel-logging` | 用于入站丢弃和 typing/ack 失败的渠道日志辅助工具 |
| `plugin-sdk/channel-inbound` | 为入站去抖动、提及匹配、提及策略辅助工具和 envelope 辅助工具提供兼容性 barrel |
| `plugin-sdk/channel-mention-gating` | 不包含更广泛入站运行时接口的精细提及策略辅助工具 |
| `plugin-sdk/channel-location` | 渠道位置上下文与格式化辅助工具 |
| `plugin-sdk/channel-logging` | 用于入站丢弃以及 typing/ack 失败的渠道日志辅助工具 |
| `plugin-sdk/channel-send-result` | 回复结果类型 |
| `plugin-sdk/channel-actions` | 渠道消息操作辅助工具，以及为插件兼容性保留的已弃用原生 schema 辅助工具 |
| `plugin-sdk/channel-targets` | 目标解析/匹配辅助工具 |
| `plugin-sdk/channel-contract` | 渠道契约类型 |
| `plugin-sdk/channel-feedback` | 反馈/reaction 连接能力 |
| `plugin-sdk/channel-secret-runtime` | 精简的 secret-contract 辅助工具，例如 `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment`，以及 secret target 类型 |
| `plugin-sdk/channel-feedback` | 反馈/reaction 接线 |
| `plugin-sdk/channel-secret-runtime` | 精细的 secret-contract 辅助工具，例如 `collectSimpleChannelFieldAssignments`、`getChannelSurface`、`pushAssignment` 和 secret target 类型 |
</Accordion>
<Accordion title="提供商子路径">
@ -87,25 +87,25 @@ x-i18n:
| --- | --- |
| `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` |
| `plugin-sdk/provider-setup` | 精选的本地/自托管提供商设置辅助工具 |
| `plugin-sdk/self-hosted-provider-setup` | 面向 OpenAI 兼容自托管提供商的专用设置辅助工具 |
| `plugin-sdk/self-hosted-provider-setup` | 专注于 OpenAI 兼容自托管提供商的设置辅助工具 |
| `plugin-sdk/cli-backend` | CLI 后端默认值 + watchdog 常量 |
| `plugin-sdk/provider-auth-runtime` | 面向提供商插件的运行时 API 密钥解析辅助工具 |
| `plugin-sdk/provider-auth-api-key` | API 密钥 onboarding/配置文件写入辅助工具，例如 `upsertApiKeyProfile` |
| `plugin-sdk/provider-auth-runtime` | 面向提供商插件的运行时 API key 解析辅助工具 |
| `plugin-sdk/provider-auth-api-key` | API key 新手引导/profile 写入辅助工具，例如 `upsertApiKeyProfile` |
| `plugin-sdk/provider-auth-result` | 标准 OAuth 认证结果构建器 |
| `plugin-sdk/provider-auth-login` | 面向提供商插件的共享交互式登录辅助工具 |
| `plugin-sdk/provider-env-vars` | 提供商认证环境变量查找辅助工具 |
| `plugin-sdk/provider-auth` | `createProviderApiKeyAuthMethod`, `ensureApiKeyFromOptionEnvOrPrompt`, `upsertAuthProfile`, `upsertApiKeyProfile`, `writeOAuthCredentials` |
| `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`、共享 replay-policy 构建器、provider-endpoint 辅助工具，以及 `normalizeNativeXaiModelId` 等 model-id 规范化辅助工具 |
| `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` |
| `plugin-sdk/provider-http` | 通用提供商 HTTP/endpoint 能力辅助工具，包括音频转录 multipart form 辅助工具 |
| `plugin-sdk/provider-web-fetch-contract` | 精简的 web-fetch 配置/选择契约辅助工具，例如 `enablePluginInConfig` 和 `WebFetchProviderPlugin` |
| `plugin-sdk/provider-auth` | `createProviderApiKeyAuthMethod`、`ensureApiKeyFromOptionEnvOrPrompt`、`upsertAuthProfile`、`upsertApiKeyProfile`、`writeOAuthCredentials` |
| `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`、`buildProviderReplayFamilyHooks`、`normalizeModelCompat`、共享 replay-policy 构建器、提供商端点辅助工具，以及诸如 `normalizeNativeXaiModelId` 之类的 model-id 规范化辅助工具 |
| `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`、`buildSingleProviderApiKeyCatalog`、`supportsNativeStreamingUsageCompat`、`applyProviderNativeStreamingUsageCompat` |
| `plugin-sdk/provider-http` | 通用提供商 HTTP/端点能力辅助工具，包括音频转录 multipart form 辅助工具 |
| `plugin-sdk/provider-web-fetch-contract` | 精细的 web-fetch 配置/选择契约辅助工具，例如 `enablePluginInConfig` 和 `WebFetchProviderPlugin` |
| `plugin-sdk/provider-web-fetch` | web-fetch 提供商注册/缓存辅助工具 |
| `plugin-sdk/provider-web-search-config-contract` | 面向无需插件启用连接能力的提供商的精简 web-search 配置/凭证辅助工具 |
| `plugin-sdk/provider-web-search-contract` | 精简的 web-search 配置/凭证契约辅助工具，例如 `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig`，以及作用域化凭证 setter/getter |
| `plugin-sdk/provider-web-search-config-contract` | 面向不需要插件启用接线的提供商的精细 web-search 配置/凭证辅助工具 |
| `plugin-sdk/provider-web-search-contract` | 精细的 web-search 配置/凭证契约辅助工具，例如 `createWebSearchProviderContractFields`、`enablePluginInConfig`、`resolveProviderWebSearchPluginConfig` 以及带作用域的凭证 setter/getter |
| `plugin-sdk/provider-web-search` | web-search 提供商注册/缓存/运行时辅助工具 |
| `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, Gemini schema 清理 + 诊断，以及 `resolveXaiModelCompatPatch` / `applyXaiModelCompat` 等 xAI 兼容性辅助工具 |
| `plugin-sdk/provider-usage` | `fetchClaudeUsage` 等 |
| `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`、流包装器类型，以及共享的 Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot 包装器辅助工具 |
| `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`、`buildProviderToolCompatFamilyHooks`、Gemini schema 清理 + 诊断，以及诸如 `resolveXaiModelCompatPatch` / `applyXaiModelCompat` 之类的 xAI 兼容辅助工具 |
| `plugin-sdk/provider-usage` | `fetchClaudeUsage` 及类似能力 |
| `plugin-sdk/provider-stream` | `ProviderStreamFamily`、`buildProviderStreamFamilyHooks`、`composeProviderStreamWrappers`、流包装器类型，以及共享的 Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot 包装器辅助工具 |
| `plugin-sdk/provider-transport-runtime` | 原生提供商传输辅助工具，例如受保护的 fetch、传输消息转换和可写传输事件流 |
| `plugin-sdk/provider-onboard` | 新手引导配置补丁辅助工具 |
| `plugin-sdk/global-singleton` | 进程本地 singleton/map/cache 辅助工具 |
@ -116,25 +116,26 @@ x-i18n:
| --- | --- |
| `plugin-sdk/command-auth` | `resolveControlCommandGate`、命令注册表辅助工具、发送者授权辅助工具 |
| `plugin-sdk/command-status` | 命令/帮助消息构建器，例如 `buildCommandsMessagePaginated` 和 `buildHelpMessage` |
| `plugin-sdk/approval-auth-runtime` | 审批人解析和同聊天 action-auth 辅助工具 |
| `plugin-sdk/approval-client-runtime` | 原生 exec 审批配置文件/过滤器辅助工具 |
| `plugin-sdk/approval-auth-runtime` | 审批人解析和同一聊天操作认证辅助工具 |
| `plugin-sdk/approval-client-runtime` | 原生 exec 审批 profile/filter 辅助工具 |
| `plugin-sdk/approval-delivery-runtime` | 原生审批能力/投递适配器 |
| `plugin-sdk/approval-gateway-runtime` | 共享的审批 Gateway 网关解析辅助工具 |
| `plugin-sdk/approval-handler-adapter-runtime` | 面向热渠道入口点的轻量级原生审批适配器加载辅助工具 |
| `plugin-sdk/approval-handler-runtime` | 更广泛的审批处理器运行时辅助工具；如果更精简的 adapter/gateway 接口已经足够，优先使用它们 |
| `plugin-sdk/approval-handler-adapter-runtime` | 面向高频渠道入口点的轻量级原生审批适配器加载辅助工具 |
| `plugin-sdk/approval-handler-runtime` | 范围更广的审批处理器运行时辅助工具；如果更精细的 adapter/gateway 接口已足够，优先使用它们 |
| `plugin-sdk/approval-native-runtime` | 原生审批目标 + 账户绑定辅助工具 |
| `plugin-sdk/approval-reply-runtime` | exec/插件审批回复负载辅助工具 |
| `plugin-sdk/channel-contract-testing` | 不包含宽泛 testing barrel 的精细渠道契约测试辅助工具 |
| `plugin-sdk/command-auth-native` | 原生命令认证 + 原生会话目标辅助工具 |
| `plugin-sdk/command-detection` | 共享的命令检测辅助工具 |
| `plugin-sdk/command-primitives-runtime` | 面向热渠道路径的轻量级命令文本谓词 |
| `plugin-sdk/command-surface` | 命令主体规范化和命令接口辅助工具 |
| `plugin-sdk/command-detection` | 共享命令检测辅助工具 |
| `plugin-sdk/command-primitives-runtime` | 面向高频渠道路径的轻量级命令文本谓词 |
| `plugin-sdk/command-surface` | 命令主体规范化和命令 surface 辅助工具 |
| `plugin-sdk/allow-from` | `formatAllowFromLowercase` |
| `plugin-sdk/channel-secret-runtime` | 面向渠道/插件 secret 接口的精简 secret-contract 收集辅助工具 |
| `plugin-sdk/secret-ref-runtime` | 面向 secret-contract/配置解析的精简 `coerceSecretRef` 和 SecretRef 类型辅助工具 |
| `plugin-sdk/channel-secret-runtime` | 面向渠道/插件 secret surface 的精细 secret-contract 收集辅助工具 |
| `plugin-sdk/secret-ref-runtime` | 面向 secret-contract/配置解析的精细 `coerceSecretRef` 和 SecretRef 类型辅助工具 |
| `plugin-sdk/security-runtime` | 共享的信任、私信门控、外部内容和 secret 收集辅助工具 |
| `plugin-sdk/ssrf-policy` | 主机 allowlist 和私有网络 SSRF 策略辅助工具 |
| `plugin-sdk/ssrf-dispatcher` | 不带广泛基础设施运行时接口的精简 pinned-dispatcher 辅助工具 |
| `plugin-sdk/ssrf-runtime` | pinned-dispatcher、受 SSRF 防护的 fetch 和 SSRF 策略辅助工具 |
| `plugin-sdk/ssrf-dispatcher` | 不包含宽泛基础设施运行时接口的精细 pinned-dispatcher 辅助工具 |
| `plugin-sdk/ssrf-runtime` | pinned-dispatcher、受 SSRF 保护的 fetch 和 SSRF 策略辅助工具 |
| `plugin-sdk/secret-input` | secret 输入解析辅助工具 |
| `plugin-sdk/webhook-ingress` | webhook 请求/目标辅助工具 |
| `plugin-sdk/webhook-request-guards` | 请求体大小/超时辅助工具 |
@ -143,9 +144,9 @@ x-i18n:
<Accordion title="运行时与存储子路径">
| 子路径 | 关键导出 |
| --- | --- |
| `plugin-sdk/runtime` | 广泛的运行时/日志/备份/插件安装辅助工具 |
| `plugin-sdk/runtime-env` | 精简的运行时环境、logger、超时、重试和退避辅助工具 |
| `plugin-sdk/channel-runtime-context` | 通用渠道运行时上下文注册和查找辅助工具 |
| `plugin-sdk/runtime` | 范围广泛的运行时/日志/备份/插件安装辅助工具 |
| `plugin-sdk/runtime-env` | 精细的运行时环境、日志器、超时、重试和退避辅助工具 |
| `plugin-sdk/channel-runtime-context` | 通用渠道运行时上下文注册与查找辅助工具 |
| `plugin-sdk/runtime-store` | `createPluginRuntimeStore` |
| `plugin-sdk/plugin-runtime` | 共享的插件命令/hook/http/交互式辅助工具 |
| `plugin-sdk/hook-runtime` | 共享的 webhook/内部 hook 管道辅助工具 |
@ -154,58 +155,58 @@ x-i18n:
| `plugin-sdk/cli-runtime` | CLI 格式化、等待和版本辅助工具 |
| `plugin-sdk/gateway-runtime` | Gateway 网关客户端和渠道状态补丁辅助工具 |
| `plugin-sdk/config-runtime` | 配置加载/写入辅助工具，以及插件配置查找辅助工具 |
| `plugin-sdk/telegram-command-config` | Telegram 命令名称/描述规范化以及重复/冲突检查，即使 bundled Telegram 契约接口不可用时也可使用 |
| `plugin-sdk/text-autolink-runtime` | 不依赖广泛 text-runtime barrel 的文件引用自动链接检测 |
| `plugin-sdk/approval-runtime` | exec/插件审批辅助工具、审批能力构建器、认证/配置文件辅助工具、原生路由/运行时辅助工具 |
| `plugin-sdk/telegram-command-config` | Telegram 命令名称/描述规范化，以及重复/冲突检查，即使 bundled Telegram 契约接口不可用也可使用 |
| `plugin-sdk/text-autolink-runtime` | 不包含宽泛 text-runtime barrel 的文件引用自动链接检测 |
| `plugin-sdk/approval-runtime` | exec/插件审批辅助工具、审批能力构建器、认证/profile 辅助工具、原生路由/运行时辅助工具 |
| `plugin-sdk/reply-runtime` | 共享的入站/回复运行时辅助工具、分块、分发、心跳、回复规划器 |
| `plugin-sdk/reply-dispatch-runtime` | 精简的回复分发/收尾辅助工具 |
| `plugin-sdk/reply-history` | 共享的短窗口回复历史辅助工具，例如 `buildHistoryContext`、`recordPendingHistoryEntry` 和 `clearHistoryEntriesIfEnabled` |
| `plugin-sdk/reply-dispatch-runtime` | 精细的回复分发/完成辅助工具 |
| `plugin-sdk/reply-history` | 共享的短时间窗口回复历史辅助工具，例如 `buildHistoryContext`、`recordPendingHistoryEntry` 和 `clearHistoryEntriesIfEnabled` |
| `plugin-sdk/reply-reference` | `createReplyReferencePlanner` |
| `plugin-sdk/reply-chunking` | 精简的文本/Markdown 分块辅助工具 |
| `plugin-sdk/reply-chunking` | 精细的文本/Markdown 分块辅助工具 |
| `plugin-sdk/session-store-runtime` | 会话存储路径 + updated-at 辅助工具 |
| `plugin-sdk/state-paths` | 状态/OAuth 目录路径辅助工具 |
| `plugin-sdk/routing` | 路由/会话键/账户绑定辅助工具，例如 `resolveAgentRoute`、`buildAgentSessionKey` 和 `resolveDefaultAgentBoundAccountId` |
| `plugin-sdk/status-helpers` | 共享的渠道/账户状态摘要辅助工具、运行时状态默认值以及问题元数据辅助工具 |
| `plugin-sdk/status-helpers` | 共享的渠道/账户状态摘要辅助工具、运行时状态默认值和问题元数据辅助工具 |
| `plugin-sdk/target-resolver-runtime` | 共享的目标解析器辅助工具 |
| `plugin-sdk/string-normalization-runtime` | slug/字符串规范化辅助工具 |
| `plugin-sdk/request-url` | 从 fetch/request 类输入中提取字符串 URL |
| `plugin-sdk/run-command` | 带超时的命令运行器，输出已规范化的 stdout/stderr 结果 |
| `plugin-sdk/run-command` | 带超时的命令运行器，返回规范化的 stdout/stderr 结果 |
| `plugin-sdk/param-readers` | 通用工具/CLI 参数读取器 |
| `plugin-sdk/tool-payload` | 从工具结果对象中提取规范化负载 |
| `plugin-sdk/tool-send` | 从工具参数中提取标准发送目标字段 |
| `plugin-sdk/tool-send` | 从工具参数中提取规范发送目标字段 |
| `plugin-sdk/temp-path` | 共享的临时下载路径辅助工具 |
| `plugin-sdk/logging-core` | 子系统 logger 和脱敏辅助工具 |
| `plugin-sdk/logging-core` | 子系统日志器和脱敏辅助工具 |
| `plugin-sdk/markdown-table-runtime` | Markdown 表格模式辅助工具 |
| `plugin-sdk/json-store` | 小型 JSON 状态读写辅助工具 |
| `plugin-sdk/file-lock` | 可重入文件锁辅助工具 |
| `plugin-sdk/persistent-dedupe` | 磁盘后备去重缓存辅助工具 |
| `plugin-sdk/persistent-dedupe` | 磁盘支持的去重缓存辅助工具 |
| `plugin-sdk/acp-runtime` | ACP 运行时/会话和回复分发辅助工具 |
| `plugin-sdk/acp-binding-resolve-runtime` | 不引入生命周期启动导入的只读 ACP 绑定解析 |
| `plugin-sdk/agent-config-primitives` | 精简的智能体运行时 config-schema 原语 |
| `plugin-sdk/agent-config-primitives` | 精细的智能体运行时 config-schema 基元 |
| `plugin-sdk/boolean-param` | 宽松布尔参数读取器 |
| `plugin-sdk/dangerous-name-runtime` | 危险名称匹配解析辅助工具 |
| `plugin-sdk/device-bootstrap` | 设备引导和配对令牌辅助工具 |
| `plugin-sdk/extension-shared` | 共享的被动渠道、状态和环境代理辅助原语 |
| `plugin-sdk/extension-shared` | 共享的被动渠道、状态和环境代理辅助基元 |
| `plugin-sdk/models-provider-runtime` | `/models` 命令/提供商回复辅助工具 |
| `plugin-sdk/skill-commands-runtime` | Skill 命令列表辅助工具 |
| `plugin-sdk/native-command-registry` | 原生命令注册表/构建/序列化辅助工具 |
| `plugin-sdk/agent-harness` | 面向受信任插件的实验性接口，用于低层智能体 harness：harness 类型、活动运行 steer/abort 辅助工具、OpenClaw 工具桥接辅助工具，以及尝试结果实用工具 |
| `plugin-sdk/provider-zai-endpoint` | Z.AI endpoint 检测辅助工具 |
| `plugin-sdk/native-command-registry` | 原生命令注册表构建/序列化辅助工具 |
| `plugin-sdk/agent-harness` | 面向受信任插件的实验性低层智能体 harness 接口：harness 类型、活动运行 steer/abort 辅助工具、OpenClaw 工具桥接辅助工具以及 attempt 结果实用工具 |
| `plugin-sdk/provider-zai-endpoint` | Z.AI 端点检测辅助工具 |
| `plugin-sdk/infra-runtime` | 系统事件/心跳辅助工具 |
| `plugin-sdk/collection-runtime` | 小型有界缓存辅助工具 |
| `plugin-sdk/diagnostic-runtime` | 诊断标志和事件辅助工具 |
| `plugin-sdk/error-runtime` | 错误图、格式化、共享错误分类辅助工具、`isApprovalNotFoundError` |
| `plugin-sdk/fetch-runtime` | 包装后的 fetch、代理和 pinned 查找辅助工具 |
| `plugin-sdk/runtime-fetch` | 不引入代理/受保护 fetch 导入、支持 dispatcher 感知的运行时 fetch |
| `plugin-sdk/response-limit-runtime` | 不依赖广泛 media 运行时接口的有界响应体读取器 |
| `plugin-sdk/session-binding-runtime` | 不含已配置绑定路由或配对存储的当前会话绑定状态 |
| `plugin-sdk/session-store-runtime` | 不引入广泛配置写入/维护导入的会话存储读取辅助工具 |
| `plugin-sdk/context-visibility-runtime` | 不引入广泛配置/安全导入的上下文可见性解析和补充上下文过滤 |
| `plugin-sdk/string-coerce-runtime` | 不引入 Markdown/日志导入的精简原始记录/字符串强制转换与规范化辅助工具 |
| `plugin-sdk/runtime-fetch` | 具备 dispatcher 感知能力的运行时 fetch，不引入 proxy/guarded-fetch 导入 |
| `plugin-sdk/response-limit-runtime` | 不包含宽泛媒体运行时接口的有界响应体读取器 |
| `plugin-sdk/session-binding-runtime` | 当前会话绑定状态，不包含已配置绑定路由或配对存储 |
| `plugin-sdk/session-store-runtime` | 不包含宽泛配置写入/维护导入的会话存储读取辅助工具 |
| `plugin-sdk/context-visibility-runtime` | 上下文可见性解析和补充上下文过滤，不引入宽泛配置/安全导入 |
| `plugin-sdk/string-coerce-runtime` | 不引入 Markdown/日志导入的精细原始记录/字符串强制转换与规范化辅助工具 |
| `plugin-sdk/host-runtime` | 主机名和 SCP 主机规范化辅助工具 |
| `plugin-sdk/retry-runtime` | 重试配置和重试运行器辅助工具 |
| `plugin-sdk/retry-runtime` | 重试配置和重试执行器辅助工具 |
| `plugin-sdk/agent-runtime` | 智能体目录/身份/工作区辅助工具 |
| `plugin-sdk/directory-runtime` | 由配置支持的目录查询/去重 |
| `plugin-sdk/directory-runtime` | 基于配置的目录查询/去重 |
| `plugin-sdk/keyed-async-queue` | `KeyedAsyncQueue` |
</Accordion>
@ -213,31 +214,31 @@ x-i18n:
| 子路径 | 关键导出 |
| --- | --- |
| `plugin-sdk/media-runtime` | 共享的媒体获取/转换/存储辅助工具，以及媒体负载构建器 |
| `plugin-sdk/media-generation-runtime` | 共享的媒体生成故障转移辅助工具、候选项选择和缺失模型提示 |
| `plugin-sdk/media-generation-runtime` | 共享的媒体生成故障切换辅助工具、候选项选择和缺失模型提示消息 |
| `plugin-sdk/media-understanding` | 媒体理解提供商类型，以及面向提供商的图像/音频辅助导出 |
| `plugin-sdk/text-runtime` | 共享的文本/Markdown/日志辅助工具，例如对智能体可见文本的剥离、Markdown 渲染/分块/表格辅助工具、脱敏辅助工具、directive-tag 辅助工具和安全文本实用工具 |
| `plugin-sdk/text-runtime` | 共享的文本/Markdown/日志辅助工具，例如面向助手可见文本剥离、Markdown 渲染/分块/表格辅助工具、脱敏辅助工具、directive-tag 辅助工具和安全文本实用工具 |
| `plugin-sdk/text-chunking` | 出站文本分块辅助工具 |
| `plugin-sdk/speech` | 语音提供商类型，以及面向提供商的 directive、注册表和校验辅助工具 |
| `plugin-sdk/speech-core` | 共享的语音提供商类型、注册表、directive 和规范化辅助工具 |
| `plugin-sdk/realtime-transcription` | 实时转录提供商类型、注册表辅助工具和共享 WebSocket 会话辅助工具 |
| `plugin-sdk/realtime-voice` | 实时语音提供商类型和注册表辅助工具 |
| `plugin-sdk/image-generation` | 图像生成提供商类型 |
| `plugin-sdk/image-generation-core` | 共享的图像生成类型、故障转移、认证和注册表辅助工具 |
| `plugin-sdk/image-generation-core` | 共享的图像生成类型、故障切换、认证和注册表辅助工具 |
| `plugin-sdk/music-generation` | 音乐生成提供商/请求/结果类型 |
| `plugin-sdk/music-generation-core` | 共享的音乐生成类型、故障转移辅助工具、提供商查找和 model-ref 解析 |
| `plugin-sdk/music-generation-core` | 共享的音乐生成类型、故障切换辅助工具、提供商查找和 model-ref 解析 |
| `plugin-sdk/video-generation` | 视频生成提供商/请求/结果类型 |
| `plugin-sdk/video-generation-core` | 共享的视频生成类型、故障转移辅助工具、提供商查找和 model-ref 解析 |
| `plugin-sdk/video-generation-core` | 共享的视频生成类型、故障切换辅助工具、提供商查找和 model-ref 解析 |
| `plugin-sdk/webhook-targets` | webhook 目标注册表和路由安装辅助工具 |
| `plugin-sdk/webhook-path` | webhook 路径规范化辅助工具 |
| `plugin-sdk/web-media` | 共享的远程/本地媒体加载辅助工具 |
| `plugin-sdk/zod` | 为插件 SDK 使用方重新导出的 `zod` |
| `plugin-sdk/zod` | 为 plugin SDK 使用者重新导出的 `zod` |
| `plugin-sdk/testing` | `installCommonResolveTargetErrorCases`、`shouldAckReaction` |
</Accordion>
<Accordion title="Memory 子路径">
| 子路径 | 关键导出 |
| --- | --- |
| `plugin-sdk/memory-core` | bundled memory-core 辅助接口，用于 manager/config/file/CLI 辅助工具 |
| `plugin-sdk/memory-core` | bunded memory-core 辅助接口，用于 manager/config/file/CLI 辅助工具 |
| `plugin-sdk/memory-core-engine-runtime` | Memory 索引/搜索运行时门面 |
| `plugin-sdk/memory-core-host-engine-foundation` | Memory host foundation engine 导出 |
| `plugin-sdk/memory-core-host-engine-embeddings` | Memory host embedding 契约、注册表访问、本地提供商，以及通用批处理/远程辅助工具 |
@ -251,24 +252,24 @@ x-i18n:
| `plugin-sdk/memory-core-host-runtime-cli` | Memory host CLI 运行时辅助工具 |
| `plugin-sdk/memory-core-host-runtime-core` | Memory host 核心运行时辅助工具 |
| `plugin-sdk/memory-core-host-runtime-files` | Memory host 文件/运行时辅助工具 |
| `plugin-sdk/memory-host-core` | 面向厂商中立的别名，对应 memory host 核心运行时辅助工具 |
| `plugin-sdk/memory-host-events` | 面向厂商中立的别名，对应 memory host 事件日志辅助工具 |
| `plugin-sdk/memory-host-files` | 面向厂商中立的别名，对应 memory host 文件/运行时辅助工具 |
| `plugin-sdk/memory-host-markdown` | 面向 Memory 邻近插件的共享托管 Markdown 辅助工具 |
| `plugin-sdk/memory-host-search` | 用于访问 search-manager 的活动 Memory 运行时门面 |
| `plugin-sdk/memory-host-status` | 面向厂商中立的别名，对应 memory host 状态辅助工具 |
| `plugin-sdk/memory-host-core` | 面向不同供应商的 memory host 核心运行时辅助工具别名 |
| `plugin-sdk/memory-host-events` | 面向不同供应商的 memory host 事件日志辅助工具别名 |
| `plugin-sdk/memory-host-files` | 面向不同供应商的 memory host 文件/运行时辅助工具别名 |
| `plugin-sdk/memory-host-markdown` | 面向 memory 邻接插件的共享托管 Markdown 辅助工具 |
| `plugin-sdk/memory-host-search` | 用于访问 search-manager 的 active memory 运行时门面 |
| `plugin-sdk/memory-host-status` | 面向不同供应商的 memory host 状态辅助工具别名 |
| `plugin-sdk/memory-lancedb` | bundled memory-lancedb 辅助接口 |
</Accordion>
<Accordion title="保留的 bundled-helper 子路径">
| 系列 | 当前子路径 | 预期用途 |
| 家族 | 当前子路径 | 预期用途 |
| --- | --- | --- |
| Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | bundled 浏览器插件支持辅助工具（`browser-support` 仍然是兼容性 barrel） |
| Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | bundled browser 插件支持辅助工具（`browser-support` 仍是兼容性 barrel） |
| Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | bundled Matrix 辅助/运行时接口 |
| Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | bundled LINE 辅助/运行时接口 |
| IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | bundled IRC 辅助接口 |
| 渠道专用辅助工具 | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | bundled 渠道兼容性/辅助接口 |
| 认证/插件专用辅助工具 | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | bundled 功能/插件辅助接口；`plugin-sdk/github-copilot-token` 当前导出 `DEFAULT_COPILOT_API_BASE_URL`、`deriveCopilotApiBaseUrlFromToken` 和 `resolveCopilotApiToken` |
| 渠道特定辅助工具 | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | bundled 渠道兼容性/辅助接口 |
| 认证/插件特定辅助工具 | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | bundled 功能/插件辅助接口；`plugin-sdk/github-copilot-token` 当前导出 `DEFAULT_COPILOT_API_BASE_URL`、`deriveCopilotApiBaseUrlFromToken` 和 `resolveCopilotApiToken` |
</Accordion>
</AccordionGroup>

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

@ -3,48 +3,47 @@ read_when:
- 你想在 OpenClaw 中使用 OpenAI 模型
- 你想使用 Codex 订阅认证，而不是 API 密钥
- 你需要更严格的 GPT-5 智能体执行行为
summary: 在 OpenClaw 中通过 API 密钥或 Codex 订阅使用 OpenAI
summary: 在 OpenClaw 中使用 OpenAI 的 API 密钥或 Codex 订阅
title: OpenAI
x-i18n:
generated_at: "2026-04-23T23:39:57Z"
generated_at: "2026-04-24T02:20:29Z"
model: gpt-5.4
provider: openai
source_hash: f3445cab47caa324314c115fb968f13c2910954b685b68a17ab9228e3184fa14
source_hash: f9bb65b29be2b69a85663b17a68560c557ffb5303ac7afa2b27548a27397af46
source_path: providers/openai.md
workflow: 15
---
OpenAI 为 GPT 模型提供开发者 API。OpenClaw 支持三种 OpenAI 系列接入路径。模型前缀决定所用路径：
OpenAI 为 GPT 模型提供开发者 API。OpenClaw 支持三种 OpenAI 系列路由。模型前缀决定所使用的路由：
- **API 密钥** — 直接访问 OpenAI Platform，并按使用量计费（`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 当前可通过订阅 / OAuth 路径在 OpenClaw 中使用：
通过 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`。
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`。
</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>` | 是 |
| 服务端 Web 搜索 | 原生 OpenAI Responses 工具 | 是，在启用 Web 搜索且未固定 provider 时 |
| 图片 | `image_generate` | 是 |
| Codex 订阅模型 | 使用 `openai-codex` OAuth 的 `openai-codex/<model>` | 是 |
| Codex app-server harness | 使用 `embeddedHarness.runtime: codex` 的 `openai/<model>` | 是 |
| 服务端网页搜索 | 原生 OpenAI Responses 工具 | 是，在启用网页搜索且未固定提供商时 |
| 图像 | `image_generate` | 是 |
| 视频 | `video_generate` | 是 |
| 文本转语音 | `messages.tts.provider: "openai"` / `tts` | 是 |
| 批量语音转文本 | `tools.media.audio` / 媒体理解 | 是 |
| 流式语音转文本 | Voice Call `streaming.provider: "openai"` | 是 |
| 实时语音 | Voice Call `realtime.provider: "openai"` | 是 |
| Embeddings | memory embedding provider | 是 |
| 流式语音转文本 | 语音通话 `streaming.provider: "openai"` | 是 |
| 实时语音 | 语音通话 `realtime.provider: "openai"` | 是 |
| Embeddings | memory embedding 提供商 | 是 |
## 入门指南
@ -52,7 +51,7 @@ Codex app-server harness 使用 `openai/gpt-5.5`。对 `openai/gpt-5.5` 的直
<Tabs>
<Tab title="API 密钥（OpenAI Platform）">
**最适合：** 直接 API 访问和按使用量计费。
**最适合：** 直接访问 API 和按量计费。
<Steps>
<Step title="获取你的 API 密钥">
@ -69,25 +68,25 @@ Codex app-server harness 使用 `openai/gpt-5.5`。对 `openai/gpt-5.5` 的直
openclaw onboard --openai-api-key "$OPENAI_API_KEY"
```
</Step>
<Step title="验证模型是否可用">
<Step title="验证模型可用">
```bash
openclaw models list --provider openai
```
</Step>
</Steps>
### 路径摘要
### 路由摘要
| 模型引用 | 路径 | 认证 |
| 模型引用 | 路由 | 认证 |
|-----------|-------|------|
| `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/*`。
`openai/*` 默认是直接 OpenAI API 密钥路由，除非你显式强制使用
Codex app-server harness。GPT-5.5 本身目前仅支持订阅 / OAuth；
对于通过默认 PI runner 使用的 Codex OAuth，请使用 `openai-codex/*`。
</Note>
### 配置示例
@ -120,7 +119,7 @@ Codex app-server harness 使用 `openai/gpt-5.5`。对 `openai/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
@ -131,23 +130,23 @@ Codex app-server harness 使用 `openai/gpt-5.5`。对 `openai/gpt-5.5` 的直
openclaw config set agents.defaults.model.primary openai-codex/gpt-5.5
```
</Step>
<Step title="验证模型是否可用">
<Step title="验证模型可用">
```bash
openclaw models list --provider openai-codex
```
</Step>
</Steps>
### 路径摘要
### 路由摘要
| 模型引用 | 路径 | 认证 |
| 模型引用 | 路由 | 认证 |
|-----------|-------|------|
| `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` provider id。
`openai-codex/*` 模型前缀也是 Codex OAuth 的显式 PI 路径。
认证 / 配置文件命令请继续使用 `openai-codex` 提供商 id。
`openai-codex/*` 模型前缀也是用于 Codex OAuth 的显式 PI 路由。
</Note>
### 配置示例
@ -159,28 +158,29 @@ Codex app-server harness 使用 `openai/gpt-5.5`。对 `openai/gpt-5.5` 的直
```
<Note>
新手引导不再从 `~/.codex` 导入 OAuth 材料。请使用浏览器 OAuth（默认）或上面的设备码流程登录——OpenClaw 会在它自己的智能体认证存储中管理生成的凭证。
新手引导不再从 `~/.codex` 导入 OAuth 材料。请使用浏览器 OAuth（默认）或上述设备码流程登录——OpenClaw 会在它自己的智能体认证存储中管理生成的凭证。
</Note>
### 状态指示器
聊天中的 `/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`。
聊天中的 `/status` 会显示当前会话正在使用哪个嵌入式 harness。
默认的 PI harness 显示为 `Runner: pi (embedded)`，且不会
额外添加单独标记。选择内置的 Codex app-server harness 时，
`/status` 会在 `Fast` 后附加非 PI harness id，例如
`Fast · codex`。现有会话会保留其记录的 harness id，因此如果你在修改
`embeddedHarness` 后希望 `/status` 反映新的 PI/Codex 选择，请使用
`/new` 或 `/reset`。
### 上下文窗口上限
OpenClaw 将模型元数据与运行时上下文上限视为两个独立的值。
OpenClaw 将模型元数据和运行时上下文上限视为两个独立的值。
对于通过 Codex OAuth 使用的 `openai-codex/gpt-5.5`：
- 原生 `contextWindow`：`1000000`
- 默认运行时 `contextTokens` 上限：`272000`
在实践中，较小的默认上限通常具有更好的延迟和质量表现。你可以使用 `contextTokens` 覆盖它：
在实际使用中，较小的默认上限通常具有更好的延迟和质量表现。你可以通过 `contextTokens` 覆盖它：
```json5
{
@ -201,21 +201,20 @@ Codex app-server harness 使用 `openai/gpt-5.5`。对 `openai/gpt-5.5` 的直
</Tab>
</Tabs>
## 图片生成
## 图像生成
内置的 `openai` 插件通过 `image_generate` 工具注册图片生成功能。
它同时支持 OpenAI API 密钥图片生成，以及通过同一个 `openai/gpt-image-2` 模型引用进行的
Codex OAuth 图片生成。
内置的 `openai` 插件通过 `image_generate` 工具注册图像生成功能。
它支持使用同一个 `openai/gpt-image-2` 模型引用，同时进行基于 OpenAI API 密钥的图像生成和基于 Codex OAuth 的图像生成。
| 能力 | OpenAI API 密钥 | Codex OAuth |
| ------------------------- | ---------------------------------- | ------------------------------------ |
| 模型引用 | `openai/gpt-image-2` | `openai/gpt-image-2` |
| 认证 | `OPENAI_API_KEY` | OpenAI Codex OAuth 登录 |
| 传输 | OpenAI Images API | Codex Responses 后端 |
| 每次请求的最大图片数 | 4 | 4 |
| 编辑模式 | 已启用（最多 5 张参考图片） | 已启用（最多 5 张参考图片） |
| 每次请求最大图像数 | 4 | 4 |
| 编辑模式 | 已启用（最多 5 张参考图像） | 已启用（最多 5 张参考图像） |
| 尺寸覆盖 | 支持，包括 2K/4K 尺寸 | 支持，包括 2K/4K 尺寸 |
| 宽高比 / 分辨率 | 不会转发到 OpenAI Images API | 在安全可行时映射为受支持的尺寸 |
| 宽高比 / 分辨率 | 不会转发到 OpenAI Images API | 在安全情况下映射为受支持的尺寸 |
```json5
{
@ -228,32 +227,32 @@ Codex OAuth 图片生成。
```
<Note>
有关共享工具参数、provider 选择和故障切换行为，请参见 [图片生成](/zh-CN/tools/image-generation)。
有关共享工具参数、提供商选择和故障切换行为，请参阅 [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 Responses 后端发送图片请求。它不会先尝试 `OPENAI_API_KEY`，也不会在该
请求中静默回退到 API 密钥。如果你想使用直接 OpenAI Images API
路径，请使用 API 密钥、自定义 base URL 或 Azure 端点显式配置 `models.providers.openai`。
如果该自定义图片端点位于受信任的局域网 / 私有地址上，还要设置
`browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true`；若没有这个显式启用项，
OpenClaw 会继续阻止私有 / 内部的 OpenAI 兼容图片端点。
对于 Codex OAuth 安装，请继续使用相同的 `openai/gpt-image-2` 引用。
当配置了 `openai-codex` OAuth 配置文件时，OpenClaw 会解析该存储的 OAuth
访问令牌，并通过 Codex Responses 后端发送图像请求。它不会先尝试 `OPENAI_API_KEY`，也不会为该请求静默回退到 API 密钥。
当你希望改为使用直接 OpenAI Images API 路由时，请显式配置
`models.providers.openai`，提供 API 密钥、自定义 base URL 或 Azure 端点。
如果该自定义图像端点位于受信任的局域网 / 私有地址上，还需设置
`browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true`；除非提供此显式启用项，
否则 OpenClaw 会继续阻止私有 / 内部的兼容 OpenAI 图像端点。
生成：
```
/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="为 macOS 上的 OpenClaw 制作一张精致的发布海报" size=3840x2160 count=1
```
编辑：
```
/tool image_generate model=openai/gpt-image-2 prompt="Preserve the object shape, change the material to translucent glass" image=/path/to/reference.png size=1024x1536
/tool image_generate model=openai/gpt-image-2 prompt="保留物体形状，将材质改为半透明玻璃" image=/path/to/reference.png size=1024x1536
```
## 视频生成
@ -264,9 +263,9 @@ OpenClaw 会继续阻止私有 / 内部的 OpenAI 兼容图片端点。
| ---------------- | --------------------------------------------------------------------------------- |
| 默认模型 | `openai/sora-2` |
| 模式 | 文生视频、图生视频、单视频编辑 |
| 参考输入 | 1 张图片或 1 个视频 |
| 参考输入 | 1 张图像或 1 个视频 |
| 尺寸覆盖 | 支持 |
| 其他覆盖项 | `aspectRatio`、`resolution`、`audio`、`watermark` 会被忽略，并给出工具警告 |
| 其他覆盖项 | `aspectRatio`、`resolution`、`audio`、`watermark` 会被忽略，并显示工具警告 |
```json5
{
@ -279,16 +278,16 @@ OpenClaw 会继续阻止私有 / 内部的 OpenAI 兼容图片端点。
```
<Note>
有关共享工具参数、provider 选择和故障切换行为，请参见 [视频生成](/zh-CN/tools/video-generation)。
有关共享工具参数、提供商选择和故障切换行为，请参阅 [Video Generation](/zh-CN/tools/video-generation)。
</Note>
## GPT-5 提示词贡献
OpenClaw 会为跨 provider 的 GPT-5 系列运行添加共享的 GPT-5 提示词贡献。它按模型 id 应用，因此 `openai-codex/gpt-5.5`、`openai/gpt-5.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 行为和 heartbeat 覆盖层，因此，即使 Codex 接管了 harness 提示词的其余部分，通过 `embeddedHarness.runtime: "codex"` 强制使用的 `openai/gpt-5.x` 会话，仍会保留相同的后续执行与主动 heartbeat 指导。
内置的原生 Codex harness 通过 Codex app-server 开发者指令使用相同的 GPT-5 行为和心跳叠加层，因此，即使 Codex 接管了 harness 提示词的其余部分，强制通过 `embeddedHarness.runtime: "codex"` 的 `openai/gpt-5.x` 会话仍会保持相同的后续执行和主动心跳指引。
GPT-5 提示词贡献增加了一个带标签的行为契约，涵盖 persona 持续性、执行安全性、工具纪律、输出结构、完成检查和验证。渠道特定的回复和静默消息行为仍保留在共享的 OpenClaw 系统提示词和出站投递策略中。GPT-5 指导对匹配的模型始终启用。友好的交互风格层则是独立且可配置的。
GPT-5 提示词贡献增加了一个带标签的行为契约，涵盖 persona 持续性、执行安全性、工具纪律、输出形状、完成检查和验证。渠道特定的回复和静默消息行为仍保留在共享的 OpenClaw 系统提示词和出站传递策略中。GPT-5 指引始终会为匹配的模型启用。友好的交互风格层是独立的，并且可配置。
| 值 | 效果 |
| ---------------------- | ------------------------------------------- |
@ -318,30 +317,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` 表面注册了语音合成功能。
内置的 `openai` 插件为 `messages.tts` 界面注册了语音合成功能。
| 设置 | 配置路径 | 默认值 |
|---------|------------|---------|
| 模型 | `messages.tts.providers.openai.model` | `gpt-4o-mini-tts` |
| 语音 | `messages.tts.providers.openai.voice` | `coral` |
| 音色 | `messages.tts.providers.openai.voice` | `coral` |
| 速度 | `messages.tts.providers.openai.speed` | （未设置） |
| 指令 | `messages.tts.providers.openai.instructions` | （未设置，仅 `gpt-4o-mini-tts`） |
| 格式 | `messages.tts.providers.openai.responseFormat` | 语音便笺使用 `opus`，文件使用 `mp3` |
| 格式 | `messages.tts.providers.openai.responseFormat` | 语音便笺为 `opus`，文件为 `mp3` |
| API 密钥 | `messages.tts.providers.openai.apiKey` | 回退到 `OPENAI_API_KEY` |
| Base URL | `messages.tts.providers.openai.baseUrl` | `https://api.openai.com/v1` |
可用模型：`gpt-4o-mini-tts`、`tts-1`、`tts-1-hd`。可用语音：`alloy`、`ash`、`ballad`、`cedar`、`coral`、`echo`、`fable`、`juniper`、`marin`、`onyx`、`nova`、`sage`、`shimmer`、`verse`。
可用模型：`gpt-4o-mini-tts`、`tts-1`、`tts-1-hd`。可用音色：`alloy`、`ash`、`ballad`、`cedar`、`coral`、`echo`、`fable`、`juniper`、`marin`、`onyx`、`nova`、`sage`、`shimmer`、`verse`。
```json5
{
@ -363,16 +362,16 @@ 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：
要强制将 OpenAI 用于入站音频转录：
```json5
{
@ -392,12 +391,13 @@ GPT-5 提示词贡献增加了一个带标签的行为契约，涵盖 persona
}
```
当共享音频媒体配置或每次调用的转写请求提供了语言和提示信息时，这些信息会转发给 OpenAI。
当由共享音频媒体配置或按次转录请求提供语言和提示词提示时，
这些信息会转发给 OpenAI。
</Accordion>
<Accordion title="实时转写">
内置的 `openai` 插件为 Voice Call 插件注册了实时转写功能。
<Accordion title="实时转录">
内置的 `openai` 插件为 Voice Call 插件注册了实时转录功能。
| 设置 | 配置路径 | 默认值 |
|---------|------------|---------|
@ -409,7 +409,7 @@ GPT-5 提示词贡献增加了一个带标签的行为契约，涵盖 persona
| API 密钥 | `...openai.apiKey` | 回退到 `OPENAI_API_KEY` |
<Note>
使用到 `wss://api.openai.com/v1/realtime` 的 WebSocket 连接，并采用 G.711 u-law（`g711_ulaw` / `audio/pcmu`）音频。这一流式 provider 用于 Voice Call 的实时转写路径；Discord 语音当前仍会录制短片段，并改用批量 `tools.media.audio` 转写路径。
使用到 `wss://api.openai.com/v1/realtime` 的 WebSocket 连接，并采用 G.711 u-law（`g711_ulaw` / `audio/pcmu`）音频。这个流式提供商用于 Voice Call 的实时转录路径；Discord 语音目前则会录制短片段，并改用批量 `tools.media.audio` 转录路径。
</Note>
</Accordion>
@ -420,7 +420,7 @@ GPT-5 提示词贡献增加了一个带标签的行为契约，涵盖 persona
| 设置 | 配置路径 | 默认值 |
|---------|------------|---------|
| 模型 | `plugins.entries.voice-call.config.realtime.providers.openai.model` | `gpt-realtime-1.5` |
| 语音 | `...openai.voice` | `alloy` |
| 音色 | `...openai.voice` | `alloy` |
| Temperature | `...openai.temperature` | `0.8` |
| VAD 阈值 | `...openai.vadThreshold` | `0.5` |
| 静音时长 | `...openai.silenceDurationMs` | `500` |
@ -435,27 +435,27 @@ GPT-5 提示词贡献增加了一个带标签的行为契约，涵盖 persona
## Azure OpenAI 端点
内置的 `openai` provider 可通过覆盖 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 提供的区域数据驻留或合规控制
- 你希望将流量保留在现有 Azure 租户内部
- 你希望将流量保留在现有的 Azure 租户内
### 配置
对于通过内置 `openai` provider 进行的 Azure 图片生成，请将
`models.providers.openai.baseUrl` 指向你的 Azure 资源，并将 `apiKey` 设置为
Azure OpenAI 密钥（而不是 OpenAI Platform 密钥）：
对于通过内置 `openai` 提供商进行的 Azure 图像生成，请将
`models.providers.openai.baseUrl` 指向你的 Azure 资源，并将 `apiKey`
设置为 Azure OpenAI 密钥（而不是 OpenAI Platform 密钥）：
```json5
{
@ -470,32 +470,32 @@ Azure OpenAI 密钥（而不是 OpenAI Platform 密钥）：
}
```
OpenClaw 会将以下 Azure 主机后缀识别为 Azure 图片生成
路径：
OpenClaw 会将以下 Azure 主机后缀识别为 Azure 图像生成
路由：
- `*.openai.azure.com`
- `*.services.ai.azure.com`
- `*.cognitiveservices.azure.com`
对于发往已识别 Azure 主机的图片生成请求，OpenClaw 会：
对于发送到已识别 Azure 主机的图像生成请求，OpenClaw 会：
- 发送 `api-key` 头，而不是 `Authorization: Bearer`
- 使用按 deployment 划分的路径（`/openai/deployments/{deployment}/...`）
- 发送 `api-key` 请求头，而不是 `Authorization: Bearer`
- 使用基于 deployment 的路径（`/openai/deployments/{deployment}/...`）
- 为每个请求追加 `?api-version=...`
其他 base URL（公共 OpenAI、OpenAI 兼容代理）会继续使用标准的
OpenAI 图片请求格式。
其他 base URL（公共 OpenAI、兼容 OpenAI 的代理）会继续使用标准的
OpenAI 图像请求格式。
<Note>
`openai` provider 的 Azure 图片生成路径需要
OpenClaw 2026.4.22 或更高版本。更早版本会将任何自定义
`openai.baseUrl` 视为公共 OpenAI 端点处理，因此在 Azure
图片 deployment 上会失败。
`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"
@ -505,56 +505,52 @@ export AZURE_OPENAI_API_VERSION="2024-12-01-preview"
### 模型名称就是 deployment 名称
Azure OpenAI 会将模型绑定到 deployment。对于通过内置 `openai` provider 路由的 Azure 图片生成请求，OpenClaw 中的 `model` 字段必须是你在 Azure 门户中配置的 **Azure deployment 名称**，而不是公共 OpenAI 模型 id。
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="A clean poster" size=1024x1024 count=1
/tool image_generate model=openai/gpt-image-2-prod prompt="一张简洁的海报" size=1024x1024 count=1
```
同样的 deployment 名称规则也适用于通过内置 `openai` provider 路由的图片生成调用。
同样的 deployment 名称规则也适用于通过内置 `openai` 提供商路由的图像生成调用。
### 区域可用性
Azure 图片生成当前仅在部分区域可用
Azure 图像生成目前仅在部分区域可用
（例如 `eastus2`、`swedencentral`、`polandcentral`、`westus3`、
`uaenorth`）。在创建 deployment 之前，请先检查 Microsoft 当前的
区域列表，并确认你的区域提供了相应的特定模型。
`uaenorth`）。创建 deployment 之前，请先查看微软当前的区域列表，并确认你的区域提供相应的具体模型。
### 参数差异
Azure OpenAI 与公共 OpenAI 并不总是接受相同的图片参数。
Azure 可能会拒绝公共 OpenAI 允许的某些选项（例如在 `gpt-image-2` 上的某些
`background` 值），或者只在特定模型版本上提供这些选项。这些差异来自 Azure 和底层模型本身，而不是
OpenClaw。如果 Azure 请求因验证错误失败，请在
Azure 门户中检查你的特定 deployment 和 API 版本所支持的
参数集。
Azure OpenAI 和公共 OpenAI 并不总是接受相同的图像参数。
Azure 可能会拒绝公共 OpenAI 允许的某些选项（例如 `gpt-image-2` 上的某些
`background` 值），或者仅在特定模型版本上提供这些选项。这些差异来自 Azure 和底层模型，而不是 OpenClaw。如果 Azure 请求因验证错误而失败，请在 Azure 门户中检查你的具体 deployment 和 API 版本所支持的参数集。
<Note>
Azure OpenAI 使用原生传输和兼容行为，但不会接收
OpenClaw 的隐藏归因头——请参见 [高级配置](#advanced-configuration) 下
**原生与 OpenAI 兼容路径**
折叠面板。
OpenClaw 的隐藏归因请求头——请参阅 [高级配置](#advanced-configuration) 下的
**原生与兼容 OpenAI 的路由**
折叠项。
如果你要在 Azure 上处理聊天或 Responses 流量（不仅仅是图片生成），请使用
新手引导流程或专用的 Azure provider 配置——仅设置 `openai.baseUrl`
并不会启用 Azure 的 API / 认证格式。另有单独的
`azure-openai-responses/*` provider；请参见
下面的“服务端压缩”折叠面板。
对于 Azure 上的聊天或 Responses 流量（除图像生成之外），请使用
新手引导流程或专用的 Azure 提供商配置——仅设置 `openai.baseUrl`
并不会自动使用 Azure 的 API / 认证格式。另有一个单独的
`azure-openai-responses/*` 提供商；请参阅下方的
服务端压缩折叠项。
</Note>
## 高级配置
<AccordionGroup>
<Accordion title="传输（WebSocket 与 SSE）">
对于 `openai/*` 和 `openai-codex/*`，OpenClaw 默认都使用 WebSocket 优先、SSE 回退（`"auto"`）。
OpenClaw 对 `openai/*` 和 `openai-codex/*` 都默认采用 WebSocket 优先、SSE 回退（`"auto"`）的方式。
在 `"auto"` 模式下，OpenClaw 会：
- 在回退到 SSE 之前，重试一次早期 WebSocket 失败
- 失败后，将 WebSocket 标记为降级状态约 60 秒，并在冷却期间使用 SSE
- 为重试和重连附加稳定的会话与轮次标识头
- 在不同传输变体之间规范化使用量计数器（`input_tokens` / `prompt_tokens`）
- 在回退到 SSE 之前，对一次早期 WebSocket 失败重试一次
- 发生失败后，将 WebSocket 标记为降级约 60 秒，并在冷却期间使用 SSE
- 为重试和重连附加稳定的会话和轮次身份请求头
- 在不同传输变体之间统一使用量计数器（`input_tokens` / `prompt_tokens`）
| 值 | 行为 |
|-------|----------|
@ -586,7 +582,7 @@ OpenClaw 的隐藏归因头——请参见 [高级配置](#advanced-configuratio
</Accordion>
<Accordion title="WebSocket 预热">
OpenClaw 默认对 `openai/*` 和 `openai-codex/*` 启用 WebSocket 预热，以减少首轮延迟。
OpenClaw 默认会为 `openai/*` 和 `openai-codex/*` 启用 WebSocket 预热，以减少首轮延迟。
```json5
// 禁用预热
@ -605,13 +601,13 @@ OpenClaw 的隐藏归因头——请参见 [高级配置](#advanced-configuratio
</Accordion>
<Accordion title="Fast 模式">
OpenClaw 为 `openai/*` 和 `openai-codex/*` 提供了共享的 Fast 模式切换：
<Accordion title="快速模式">
OpenClaw 为 `openai/*` 和 `openai-codex/*` 提供了一个共享的快速模式开关：
- **聊天 / UI：** `/fast status|on|off`
- **配置：** `agents.defaults.models["<provider>/<model>"].params.fastMode`
启用后，OpenClaw 会将 Fast 模式映射为 OpenAI 优先处理（`service_tier = "priority"`）。现有的 `service_tier` 值会被保留，Fast 模式不会重写 `reasoning` 或 `text.verbosity`。
启用后，OpenClaw 会将快速模式映射到 OpenAI 的优先处理（`service_tier = "priority"`）。现有的 `service_tier` 值会被保留，快速模式不会改写 `reasoning` 或 `text.verbosity`。
```json5
{
@ -626,13 +622,13 @@ OpenClaw 的隐藏归因头——请参见 [高级配置](#advanced-configuratio
```
<Note>
会话覆盖的优先级高于配置。在 Sessions UI 中清除会话覆盖后，会话会恢复为配置中的默认值。
会话覆盖优先于配置。在 Sessions UI 中清除会话覆盖后，该会话会恢复为配置的默认值。
</Note>
</Accordion>
<Accordion title="优先处理（service_tier）">
OpenAI 的 API 通过 `service_tier` 提供优先处理能力。你可以在 OpenClaw 中按模型设置它：
OpenAI 的 API 通过 `service_tier` 提供优先处理。你可以在 OpenClaw 中按模型设置它：
```json5
{
@ -649,21 +645,23 @@ OpenClaw 的隐藏归因头——请参见 [高级配置](#advanced-configuratio
支持的值：`auto`、`default`、`flex`、`priority`。
<Warning>
`serviceTier` 只会转发到原生 OpenAI 端点（`api.openai.com`）和原生 Codex 端点（`chatgpt.com/backend-api`）。如果你通过代理路由任一 provider，OpenClaw 会保持 `service_tier` 不变。
`serviceTier` 只会转发到原生 OpenAI 端点（`api.openai.com`）和原生 Codex 端点（`chatgpt.com/backend-api`）。如果你通过代理路由任一提供商，OpenClaw 会保持 `service_tier` 不变。
</Warning>
</Accordion>
<Accordion title="服务端压缩（Responses API）">
对于直接 OpenAI Responses 模型（位于 `api.openai.com` 的 `openai/*`），OpenClaw 会自动启用服务端压缩：
对于直接 OpenAI Responses 模型（`api.openai.com` 上的 `openai/*`），OpenAI 插件的 Pi-harness 流包装器会自动启用服务端压缩：
- 强制设置 `store: true`（除非模型兼容性设置了 `supportsStore: false`）
- 注入 `context_management: [{ type: "compaction", compact_threshold: ... }]`
- 默认 `compact_threshold`：`contextWindow` 的 70%（如不可用则为 `80000`）
- 默认 `compact_threshold`：`contextWindow` 的 70%（不可用时为 `80000`）
这适用于内置的 Pi harness 路径，以及嵌入式运行所使用的 OpenAI 提供商钩子。原生 Codex app-server harness 通过 Codex 自行管理上下文，并通过 `agents.defaults.embeddedHarness.runtime` 单独配置。
<Tabs>
<Tab title="显式启用">
对 Azure OpenAI Responses 这类兼容端点很有用：
对于 Azure OpenAI Responses 之类的兼容端点很有用：
```json5
{
@ -715,13 +713,13 @@ OpenClaw 的隐藏归因头——请参见 [高级配置](#advanced-configuratio
</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
{
@ -735,31 +733,31 @@ OpenClaw 的隐藏归因头——请参见 [高级配置](#advanced-configuratio
使用 `strict-agentic` 时，OpenClaw 会：
- 当工具操作可用时，不再将仅规划的轮次视为成功进展
- 通过“立即行动”的引导重试该轮
- 为实质性工作自动启用 `update_plan`
- 如果模型持续规划而不行动，则显示明确的阻塞状态
- 使用立即执行的引导重试该轮次
- 对于较大工作自动启用 `update_plan`
- 如果模型持续规划而不执行，则显示明确的阻塞状态
<Note>
仅作用于 OpenAI 和 Codex 的 GPT-5 系列运行。其他 provider 和较旧模型系列会保持默认行为。
仅适用于 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.effort: "none"` 的模型或代理省略禁用的 reasoning
- 默认将工具 schema 设为严格模式
- 仅在已验证的原生主机上附加隐藏归因头
- 保留 OpenAI 专属的请求整形（`service_tier`、`store`、reasoning 兼容性、提示词缓存提示）
- 仅在已验证的原生主机上附加隐藏归因请求头
- 保留 OpenAI 专用的请求整形（`service_tier`、`store`、reasoning 兼容性、prompt-cache 提示）
**代理 / 兼容路径：**
**代理 / 兼容路由：**
- 使用更宽松的兼容行为
- 不强制严格工具 schema，也不附加原生专用头
- 不强制严格工具 schema 或原生专用请求头
Azure OpenAI 使用原生传输与兼容行为，但不会接收隐藏归因头。
Azure OpenAI 使用原生传输和兼容行为，但不会接收隐藏归因请求头。
</Accordion>
</AccordionGroup>
@ -768,15 +766,15 @@ OpenClaw 的隐藏归因头——请参见 [高级配置](#advanced-configuratio
<CardGroup cols={2}>
<Card title="模型选择" href="/zh-CN/concepts/model-providers" icon="layers">
选择 provider、模型引用和故障切换行为。
选择提供商、模型引用和故障切换行为。
</Card>
<Card title="图片生成" href="/zh-CN/tools/image-generation" icon="image">
共享图片工具参数与 provider 选择。
<Card title="图像生成" href="/zh-CN/tools/image-generation" icon="image">
共享图像工具参数和提供商选择。
</Card>
<Card title="视频生成" href="/zh-CN/tools/video-generation" icon="video">
共享视频工具参数与 provider 选择。
共享视频工具参数和提供商选择。
</Card>
<Card title="OAuth 与认证" href="/zh-CN/gateway/authentication" icon="key">
认证细节与凭证复用规则。
认证细节和凭证复用规则。
</Card>
</CardGroup>