跳转到内容
OpenClaw Docs

OpenAIOpenAI

OpenAI 为 GPT 模型提供开发者 API，并且 Codex 也可以通过 OpenAI 的 Codex 客户端作为 ChatGPT 计划的编码代理使用。OpenClaw 对这两种身份验证形状使用同一个提供商 ID，OpenAIOpenAIOpenClawopenai。

OpenClaw 使用 OpenClawopenai/*OpenAIOpenAIOpenAIAPIOpenAI 作为 OpenAI 模型的规范路由。嵌入式代理默认开启通过原生 Codex 应用服务器运行时运行的 OpenAI 模型；直接的 OpenAI API 密钥身份验证仍可用于非代理 OpenAI 表面，例如图像、嵌入、语音和实时功能。

  • 代理模型 - 通过 Codex 运行时的 openai/*OpenAIAPIAPI 模型；登录 Codex 身份验证以使用 ChatGPT/Codex 订阅，或者当您有意使用 API 密钥身份验证时，配置一个与 Codex 兼容的 OpenAI API 密钥备份。
  • 非代理 OpenAI API - 通过 OpenAIOpenAIOPENAI_API_KEYOpenAIAPI 或 OpenAI API 密钥新手引导，使用基于使用量的计费直接访问 OpenAI 平台。
  • 旧版配置 - 旧的 Codex 模型引用由 openclaw doctor --fix 修复为 openai/* 加上 Codex 运行时。

OpenAI 明确支持在外部工具和工作流程（如 OpenClaw）中使用订阅 OAuth。

提供商、模型、运行时和渠道是独立的层级。如果这些标签混在一起，请在更改配置之前阅读 代理运行时。

快速选择

Section titled “快速选择”
目标使用备注
ChatGPT/Codex 订阅搭配原生 Codex 运行时openai/gpt-5.5默认的 OpenAI 代理设置。使用 Codex 认证登录。
代理模型的直接 API 密钥计费openai/gpt-5.5API 加上 Codex 兼容的 API 密钥配置文件使用 auth.order.openai 将备份置于订阅身份验证之后。
通过显式 APIOpenClaw 密钥直接计费openai/gpt-5.5 加上提供商/模型运行时 openclaw选择一个正常的 openaiAPI API 密钥配置文件。
最新的 ChatGPT Instant API 别名openai/chat-latest仅限直接 API 密钥。用于实验的变动别名，而非默认值。
通过 OpenClaw 进行 ChatGPT/Codex 订阅身份验证openai/gpt-5.5 加上提供商/模型运行时 openclaw为兼容性路由选择一个 openaiOAuth OAuth 配置文件。
图像生成或编辑openai/gpt-image-2适用于 OPENAI_API_KEYOpenAIOAuth 或 OpenAI Codex OAuth。
透明背景图像openai/gpt-image-1.5使用 outputFormat=png 或 webp 以及 openai.background=transparent。

命名映射

Section titled “命名映射”

名称相似但不可互换：

您看到的名称层级含义
openai提供商前缀规范的 OpenAI 模型路由；代理轮次使用 Codex 运行时。
旧的 OpenAI Codex 前缀旧版前缀较旧的模型/配置文件命名空间。openclaw doctor --fix 会将其迁移到 openai。
codex 插件插件捆绑的 OpenClaw 插件，提供原生 Codex 应用服务器运行时和 /codex 聊天控件。
提供商/模型 agentRuntime.id: codex代理运行时为匹配的嵌入式轮次强制使用原生 Codex 应用服务器容器。
/codex ...聊天命令集从对话中绑定/控制 Codex 应用服务器线程。
runtime: "acp", agentId: "codex"ACP 会话路由通过 ACP/acpx 运行 Codex 的显式回退路径。

这意味着配置可以有意识地包含 openai/* 模型引用，而身份验证配置文件指向 API 密钥或 ChatGPT/Codex OAuth 凭据。使用 auth.order.openai 进行配置；openclaw doctor --fix 会将旧版 Codex 模型引用、旧版 Codex 身份验证配置文件 ID 以及 旧版 Codex 身份验证顺序重写为 OpenAI 的规范路由。

OpenClaw 功能覆盖

Section titled “OpenClaw 功能覆盖”
OpenAI 功能OpenClaw 表面状态
聊天 / 响应openai/<model> 模型提供商是
Codex 订阅模型openai/<model> 搭配 OpenAI OAuth是
传统 Codex 模型引用旧版 Codex 模型引用或 codex-cli/<model>由 doctor 修复为 openai/<model>
Codex 应用服务器驱动器openai/<model> 且省略了 runtime 或 提供商/模型 agentRuntime.id: codex是
服务器端网页搜索原生 OpenAI 响应工具是，当启用网页搜索且未固定提供商时
图像image_generate是
视频video_generate是
文本转语音messages.tts.provider: "openai" / tts是
批量语音转文本tools.media.audio / 媒体理解是
流式语音转文本语音通话 streaming.provider: "openai"是
实时语音语音通话 realtime.provider: "openai" / 控制界面对话 talk.realtime.provider: "openai"是（需要 OpenAI Platform 额度，而非 Codex/ChatGPT 订阅）
嵌入内存嵌入提供商是

Memory embeddings

Section titled “Memory embeddings”

OpenClaw 可以使用 OpenAI 或兼容 OpenAI 的嵌入端点来进行 OpenClawOpenAIOpenAImemory_search 索引和查询嵌入：

{
  agents: {
    defaults: {
      memorySearch: {
        provider: "openai",
        model: "text-embedding-3-small",
      },
    },
  },
}

对于需要非对称嵌入标签的 OpenAI 兼容端点，请在 memorySearch 下设置 queryInputType 和 documentInputType。OpenClaw 会将这些作为提供商特定的 input_type 请求字段进行转发：查询嵌入使用 queryInputType；索引的内存块和批量索引使用 documentInputType。有关完整示例，请参阅 内存配置参考。

入门指南

Section titled “入门指南”

选择您偏好的身份验证方法并按照设置步骤进行操作。

最适合： 直接 API 访问和按使用量计费。

  1. API获取您的 API 密钥

    从 OpenAI Platform 仪表板 创建或复制 API 密钥。

  2. 运行新手引导

    Terminal window
    openclaw onboard --auth-choice openai-api-key

    或者直接传递密钥：

    Terminal window
    openclaw onboard --openai-api-key "$OPENAI_API_KEY"

  3. 验证模型是否可用

    Terminal window
    openclaw models list --provider openai

路由摘要

Section titled “路由摘要”
模型参考运行时配置路由认证
openai/gpt-5.5omitted / 提供商/模型 agentRuntime.id: "codex"OpenAICodex app-server harnessCodex-compatible OpenAI profile
openai/gpt-5.4-miniomitted / 提供商/模型 agentRuntime.id: "codex"OpenAICodex app-server harnessCodex-compatible OpenAI profile
openai/gpt-5.5提供商/模型 agentRuntime.id: "openclaw"OpenClawOpenClaw embedded runtimeSelected openai profile

配置示例

Section titled “配置示例”
{
  env: { OPENAI_API_KEY: "example-openai-key-not-real" },
  agents: { defaults: { model: { primary: "openai/gpt-5.5" } } },
}
```OpenAIAPI


要从 OpenAI API 尝试 ChatGPT 当前的 Instant 模型，请将模型设置为 `openai/chat-latest`：


```json5
{
  env: { OPENAI_API_KEY: "example-openai-key-not-real" },
  agents: { defaults: { model: { primary: "openai/chat-latest" } } },
}

chat-latestOpenAI 是一个动态别名。OpenAI 将其记录为 ChatGPT 中使用的最新 Instant 模型，并推荐 gpt-5.5API 用于生产 API 使用，因此请将 openai/gpt-5.5 保留为稳定的默认值，除非您明确需要该别名行为。该别名目前仅接受 mediumOpenClawOpenAIOpenClaw 文本详细程度，因此 OpenClaw 会针对此模型规范化不兼容的 OpenAI 文本详细程度覆盖。

原生 Codex 应用服务器认证

Section titled “原生 Codex 应用服务器认证”

原生 Codex 应用服务器连接器使用 openai/* 模型引用加上省略的运行时配置或提供商/模型 agentRuntime.id: "codex"OpenClaw，但其身份验证仍然是基于帐户的。OpenClaw 按以下顺序选择身份验证：

  1. 针对代理的已排序 OpenAI 身份验证配置文件，最好位于 OpenAIauth.order.openai 下。运行 openclaw doctor --fix 以迁移较旧的 旧版 Codex 身份验证配置文件 ID 和旧版 Codex 身份验证顺序。
  2. 应用服务器的现有账户，例如本地 Codex CLI ChatGPT 登录。
  3. 仅针对本地 stdio 应用服务器启动，先 CODEX_API_KEY，然后 OPENAI_API_KEYOpenAI，当应用服务器报告没有帐户但仍需要 OpenAI 身份验证时。

这意味着，即使网关进程也拥有用于直接 OpenAI 模型 或嵌入的 OPENAI_API_KEYOpenAIAPIOpenClaw，本地 ChatGPT/Codex 订阅登录也不会仅仅因此而被替换。环境 API 密钥回退仅适用于本地 stdio 无帐户路径；它 不会发送到 WebSocket 应用服务器连接。当选择订阅风格的 Codex 配置文件时，OpenClaw 还会将 CODEX_API_KEY 和 OPENAI_API_KEYRPCOpenClaw 排除在衍生出的 stdio 应用服务器子进程之外，并通过应用服务器登录 RPC 发送所选凭据。当该订阅配置文件被 Codex 使用限制阻止时，OpenClaw 可以轮换到下一个已排序的 openai:*API API 密钥 配置文件，而无需更改所选模型或退出 Codex 连接器。一旦订阅重置时间过去，该订阅配置文件将再次变得可用。

图像生成

Section titled “图像生成”

捆绑的 openai 插件通过 image_generateOpenAIAPIOAuth 工具注册图像生成。 它支持通过同一个 openai/gpt-image-2 模型引用进行 OpenAI API 密钥图像生成和 Codex OAuth 图像 生成。

功能OpenAI API 密钥Codex OAuth
模型参考openai/gpt-image-2openai/gpt-image-2
身份验证OPENAI_API_KEYOpenAI Codex OAuth 登录
传输OpenAI 图像 APICodex Responses 后端
每次请求的最大图像数44
编辑模式已启用（最多 5 张参考图片）已启用（最多 5 张参考图片）
尺寸覆盖支持，包括 2K/4K 尺寸支持，包括 2K/4K 尺寸
宽高比 / 分辨率不转发至 OpenAI 图像 API安全时映射到支持的尺寸
{
  agents: {
    defaults: {
      imageGenerationModel: { primary: "openai/gpt-image-2" },
    },
  },
}

gpt-image-2OpenAI 是 OpenAI 文本生成图像和图像编辑的默认模型。gpt-image-1.5、gpt-image-1 和 gpt-image-1-mini 仍可用作显式模型覆盖。使用 openai/gpt-image-1.5 获取透明背景的 PNG/WebP 输出；当前的 gpt-image-2API API 拒绝 background: "transparent"。

对于透明背景请求，代理应使用 model: "openai/gpt-image-1.5"、outputFormat: "png" 或 "webp" 以及 background: "transparent" 调用 image_generate；较旧的 openai.backgroundOpenClawOpenAIOpenAIOAuth 提供商选项仍然被接受。OpenClaw 还通过将默认的 openai/gpt-image-2 透明请求重写为 gpt-image-1.5OpenAI 来保护公共 OpenAI 和 OpenAI Codex OAuth 路由；Azure 和自定义 OpenAI 兼容端点将保留其配置的部署/模型名称。

相同的设置也适用于无头 CLI 运行：

Terminal window
openclaw infer image generate \
  --model openai/gpt-image-1.5 \
  --output-format png \
  --background transparent \
  --prompt "A simple red circle sticker on a transparent background" \
  --json

当从输入文件开始时，将相同的 --output-format 和 --background 标志与 openclaw infer image edit 一起使用。 --openai-backgroundOpenAI 仍可用作 OpenAI 专用别名。

对于 ChatGPT/Codex OAuth 安装，请保持相同的 openai/gpt-image-2 引用。当配置了 openai OAuth 配置文件时，OpenClaw 会解析该存储的 OAuth 访问令牌，并通过 Codex Responses 后端发送图像请求。它不会首先尝试 OPENAI_API_KEY 或静默回退到该请求的 API 密钥。当您需要直接的 API Images OpenAI 路由时，请使用 API 密钥、自定义基础 URL 或 Azure 端点显式配置 models.providers.openai。如果该自定义图像端点位于受信任的 LAN/专用地址上，请同时设置 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

生成透明 PNG：

/tool image_generate model=openai/gpt-image-1.5 prompt="A simple red circle sticker on a transparent background" outputFormat=png background=transparent

编辑：

/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

视频生成

Section titled “视频生成”

捆绑的 openai 插件通过 video_generate 工具注册视频生成。

能力值
默认模型openai/sora-2
模式文本生成视频、图像生成视频、单个视频编辑
参考输入1 张图像或 1 个视频
尺寸覆盖支持文本生成视频和图像生成视频
其他覆盖aspectRatio、resolution、audio、watermark 将被忽略并显示工具警告

OpenAI 图生视频请求使用带有图像 input_reference 的 POST /v1/videos。单个视频编辑使用带有 video 字段中上传视频的 POST /v1/videos/edits。

{
  agents: {
    defaults: {
      videoGenerationModel: { primary: "openai/sora-2" },
    },
  },
}

GPT-5 提示词贡献

Section titled “GPT-5 提示词贡献”

OpenClaw 为 OpenClaw 组装的提示词表面上的 GPT-5 系列运行添加了共享的 GPT-5 提示词贡献。它按模型 ID 应用，因此 OpenClaw/提供商路由（如 legacy pre-repair 引用（legacy Codex GPT-5.5 引用）、openrouter/openai/gpt-5.5、opencode/gpt-5.5 和其他兼容的 GPT-5 引用）会收到相同的覆盖。较旧的 GPT-4.x 模型则不会。

捆绑的原生 Codex 控制装置不会通过 Codex 应用服务器开发者指令接收此 OpenClaw GPT-5 叠加层。原生 Codex 保留 Codex 拥有的基础、模型和项目文档行为，而 OpenClaw 会针对原生线程禁用 Codex 的内置个性，以便代理工作区个性文件保持权威。OpenClaw 仅贡献运行时上下文，例如渠道交付、OpenClaw 动态工具、ACP 委托、工作区上下文和 OpenClaw 技能。

GPT-5 贡献为匹配的 OpenClaw 组装提示词添加了带标签的行为合约，涉及人格持久性、执行安全性、工具纪律、输出形状、完成检查和验证。特定渠道的回复和静默消息行为保留在共享的 OpenClaw 系统提示词和出站交付策略中。友好的交互样式层是独立的且可配置。

值效果
"friendly"（默认）启用友好的交互样式层
"on""friendly" 的别名
"off"仅禁用友好样式层
{
  agents: {
    defaults: {
      promptOverlays: {
        gpt5: { personality: "friendly" },
      },
    },
  },
}

语音与演讲

Section titled “语音与演讲”
语音合成 (TTS)

捆绑的 openai 插件为 messages.tts 表面注册语音合成。

设置配置路径默认值
模型messages.tts.providers.openai.modelgpt-4o-mini-tts
音色messages.tts.providers.openai.speakerVoicecoral
语速messages.tts.providers.openai.speed（未设置）
指令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 URLmessages.tts.providers.openai.baseUrlhttps://api.openai.com/v1
额外 Bodymessages.tts.providers.openai.extraBody / extra_body（未设置）

可用模型：gpt-4o-mini-tts、tts-1、tts-1-hd。可用音色：alloy、ash、ballad、cedar、coral、echo、fable、juniper、marin、onyx、nova、sage、shimmer、verse。

extraBody 会在 OpenClaw 生成的字段之后合并到 /audio/speech 请求 JSON 中，因此请将其用于需要额外键（例如 lang）的 OpenAI 兼容端点。原型键将被忽略。

{
  messages: {
    tts: {
      providers: {
        openai: { model: "gpt-4o-mini-tts", speakerVoice: "coral" },
      },
    },
  },
}
语音转文字

附带的 openaiOpenClaw 插件通过 OpenClaw 的媒体理解转录表面注册了批量语音转文字。

  • 默认模型：gpt-4o-transcribeOpenAI
  • 端点：OpenAI REST /v1/audio/transcriptionsOpenClaw
  • 输入路径：多部分音频文件上传
  • OpenClaw 在任何使用 tools.media.audioDiscordOpenAI 的入站音频转录处均提供支持，包括 Discord 语音频道片段和频道音频附件

要强制入站音频转录使用 OpenAI：

{
  tools: {
    media: {
      audio: {
        models: [
          {
            type: "provider",
            provider: "openai",
            model: "gpt-4o-transcribe",
          },
        ],
      },
    },
  },
}
```OpenAI


当通过共享音频媒体配置或每次调用的转录请求提供语言和提示时，它们会被转发给 OpenAI。
实时转录

捆绑的 openai 插件为语音通话插件注册实时转录。

设置配置路径默认值
模型plugins.entries.voice-call.config.streaming.providers.openai.modelgpt-4o-transcribe
语言...openai.language(未设置)
提示词...openai.prompt(未设置)
静音时长...openai.silenceDurationMs800
VAD 阈值...openai.vadThreshold0.5
认证...openai.apiKey、OPENAI_API_KEY 或 openaiOAuthAPIOAuth OAuthAPI keys 直接连接；OAuth 会生成一个实时转录客户端密钥
Realtime voice

捆绑的 openai 插件为 Voice Call 插件注册了实时语音功能。

设置配置路径默认值
模型plugins.entries.voice-call.config.realtime.providers.openai.modelgpt-realtime-2
语音...openai.voicealloy
温度（Azure 部署桥接）...openai.temperature0.8
VAD 阈值...openai.vadThreshold0.5
静音持续时间...openai.silenceDurationMs500
前缀填充...openai.prefixPaddingMs300
推理强度...openai.reasoningEffort（未设置）
身份验证...openai.apiKey，OPENAI_API_KEY，或 openai OAuth浏览器 Talk 和非 Azure 后端桥接可以使用 OpenAI OAuth

gpt-realtime-2 可用的内置实时语音包括：alloy、ash、 ballad、coral、echo、sage、shimmer、verse、marin、cedar。 OpenAI 推荐使用 marin 和 cedar 以获得最佳的实时质量。这是 与上述文本转语音语音不同的一组语音；不要假设 TTS 语音（如 fable、nova 或 onyx）对实时会话有效。

Azure OpenAI 端点

Section titled “Azure OpenAI 端点”

通过覆盖基础 URL，捆绑的 openaiOpenAIOpenClaw 提供商可以指定 Azure OpenAI 资源进行图像生成。在图像生成路径上，OpenClaw 会检测 models.providers.openai.baseUrl 上的 Azure 主机名，并自动切换到 Azure 的请求格式。

在以下情况下使用 Azure OpenAI：

  • 您已经拥有 Azure OpenAI 订阅、配额或企业协议
  • 您需要 Azure 提供的区域数据驻留或合规性控制
  • 您希望将流量保留在现有的 Azure 租户内

配置

Section titled “配置”

若要通过捆绑的 openai 提供商进行 Azure 图像生成，请将 models.providers.openai.baseUrl 指向您的 Azure 资源，并将 apiKeyOpenAIOpenAI 设置为 Azure OpenAI 密钥（而非 OpenAI Platform 密钥）：

{
  models: {
    providers: {
      openai: {
        baseUrl: "https://<your-resource>.openai.azure.com",
        apiKey: "<azure-openai-api-key>",
      },
    },
  },
}

OpenClaw 为 Azure 图像生成路由识别以下 Azure 主机后缀：

  • *.openai.azure.com
  • *.services.ai.azure.com
  • *.cognitiveservices.azure.com

对于已识别的 Azure 主机上的图像生成请求，OpenClaw：

  • 发送 api-key 标头而不是 Authorization: Bearer
  • 使用部署范围路径 (/openai/deployments/{deployment}/...)
  • 将 ?api-version=... 附加到每个请求
  • 对 Azure 图像生成调用使用 600 秒的默认请求超时。 每次调用的 timeoutMs 值仍会覆盖此默认值。

其他基础 URL（公共 OpenAI、兼容 OpenAI 的代理）保持标准 OpenAI 图像请求形状。

API 版本

Section titled “API 版本”

设置 AZURE_OPENAI_API_VERSION 以锁定特定的 Azure 预览版或正式版 (GA) 版本 用于 Azure 图像生成路径：

Terminal window
export AZURE_OPENAI_API_VERSION="2024-12-01-preview"

未设置变量时，默认值为 2024-12-01-preview。

模型名称即部署名称

Section titled “模型名称即部署名称”

Azure OpenAI 将模型绑定到部署。对于通过捆绑的 openai 提供商路由的 Azure 图像生成请求，OpenClaw 中的 model 字段必须是您在 Azure 门户中配置的 Azure 部署名称，而不是公共 OpenAI 模型 ID。

如果您创建一个名为 gpt-image-2-prod 的部署来提供 gpt-image-2：

/tool image_generate model=openai/gpt-image-2-prod prompt="A clean poster" size=1024x1024 count=1

相同的部署名称规则适用于通过捆绑的 openai 提供商路由的图像生成调用。

区域可用性

Section titled “区域可用性”

Azure 图像生成目前仅在部分区域可用（例如 eastus2、swedencentral、polandcentral、westus3、uaenorth）。在创建部署之前，请查看 Microsoft 当前的区域列表，并确认您的区域中是否提供特定模型。

参数差异

Section titled “参数差异”

Azure OpenAI 和公共 OpenAI 并不总是接受相同的图像参数。Azure 可能会拒绝公共 OpenAI 允许的选项（例如 gpt-image-2 上的某些 background 值），或者仅在某些特定模型版本上公开这些选项。这些差异来自 Azure 和底层模型，而非 OpenClaw。如果 Azure 请求因验证错误而失败，请在 Azure 门户中检查您的特定部署和 API 版本支持的参数集。

高级配置

Section titled “高级配置”
Transport (WebSocket vs SSE)

OpenClaw 对 openai/* 优先使用 WebSocket，SSE 作为回退 ("auto")。

在 "auto" 模式下，OpenClaw：

  • 在回退到 SSE 之前重试一次早期的 WebSocket 失败
  • 失败后，将 WebSocket 标记为降级约 60 秒，并在冷却期间使用 SSE
  • 为重试和重新连接附加稳定的会话和回合标识标头
  • 跨传输变体标准化使用计数器 (input_tokens / prompt_tokens)
ValueBehavior
"auto" (默认)WebSocket 优先，SSE 回退
"sse"强制仅使用 SSE
"websocket"强制仅使用 WebSocket
{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.5": {
          params: { transport: "auto" },
        },
      },
    },
  },
}

相关 OpenAI 文档：

Fast mode

OpenClaw 为 openai/* 提供了一个共享的快速模式开关：

  • Chat/UI: /fast status|on|off
  • Config: `agents.defaults.models[”

/

“].params.fastMode`OpenClawOpenAI

启用后，OpenClaw 会将快速模式映射到 OpenAI 优先处理（`service_tier = "priority"`）。现有的 `service_tier` 值将被保留，快速模式不会重写 `reasoning` 或 `text.verbosity`。


```json5
{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.5": { params: { fastMode: true } },
      },
    },
  },
}
```

<Accordion title=“Priority processing (service_tier)“OpenAIAPI> OpenAI 的 API 通过 service_tierOpenClaw 暴露了优先处理功能。请在 OpenClaw 中为每个模型进行设置：

```json5
{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.5": { params: { serviceTier: "priority" } },
      },
    },
  },
}
```


支持的值：`auto`、`default`、`flex`、`priority`。


<Warning>
`serviceTier`OpenAI 仅转发到原生 OpenAI 端点（`api.openai.com`）和原生 Codex 端点（`chatgpt.com/backend-api`OpenClaw）。如果您通过代理路由任一提供商，OpenClaw 将保持 `service_tier` 不变。
</Warning>

<Accordion title=“API服务器端压缩 (Responses API)“OpenAI> 对于直接 OpenAI Responses 模型（openai/* 上的 api.openai.comOpenAIOpenClaw），OpenAI 插件的 OpenClow 流包装器会自动启用服务器端压缩：

- 强制执行 `store: true`（除非模型兼容性设置了 `supportsStore: false`）
- 注入 `context_management: [{ type: "compaction", compact_threshold: ... }]`
- 默认 `compact_threshold`：`contextWindow` 的 70%（当不可用时为 `80000`OpenClawOpenAIOpenAI）


这适用于内置的 OpenClaw 运行时路径以及嵌入式运行所使用的 OpenAI 提供商挂钩。原生 Codex 应用服务器工具通过 Codex 管理其自己的上下文，并由 OpenAI 的默认代理路由或提供商/模型运行时策略进行配置。


<Tabs>
  <Tab title="显式启用"OpenAI>
    适用于兼容的端点，例如 Azure OpenAI Responses：


    ```json5
    {
      agents: {
        defaults: {
          models: {
            "azure-openai-responses/gpt-5.5": {
              params: { responsesServerCompaction: true },
            },
          },
        },
      },
    }
    ```
  </Tab>
  <Tab title="自定义阈值">
    ```json5
    {
      agents: {
        defaults: {
          models: {
            "openai/gpt-5.5": {
              params: {
                responsesServerCompaction: true,
                responsesCompactThreshold: 120000,
              },
            },
          },
        },
      },
    }
    ```
  </Tab>
  <Tab title="禁用">
    ```json5
    {
      agents: {
        defaults: {
          models: {
            "openai/gpt-5.5": {
              params: { responsesServerCompaction: false },
            },
          },
        },
      },
    }
    ```
  </Tab>
</Tabs>


<Note>
`responsesServerCompaction` 仅控制 `context_management`OpenAI 的注入。直接的 OpenAI Responses 模型仍会强制执行 `store: true`，除非兼容性设置了 `supportsStore: false`。
</Note>
Strict-agentic GPT mode

对于在 openai/*OpenClaw 上运行的 GPT-5 系列，OpenClaw 可以使用更严格的嵌入式执行契约：

{
  agents: {
    defaults: {
      embeddedAgent: { executionContract: "strict-agentic" },
    },
  },
}

通过 strict-agenticOpenClaw，OpenClaw：

  • 当工具操作可用时，不再将仅计划的回合视为成功的进展
  • 使用“立即行动”引导重试该回合
  • 为实质性工作自动启用 update_planOpenAI
  • 如果模型持续计划而不采取行动，则显示显式的阻塞状态

<Accordion title=“OpenAINative vs OpenAI-compatible routes”OpenClawOpenAIOpenAIOpenAI> OpenClaw treats direct OpenAI, Codex, and Azure OpenAI endpoints differently from generic OpenAI-compatible /v1 proxies:

**Native routes** (`openai/*`OpenAI, Azure OpenAI):
- Keep `reasoning: { effort: "none" }`OpenAI only for models that support the OpenAI `none` effort
- Omit disabled reasoning for models or proxies that reject `reasoning.effort: "none"`OpenAI
- Default 工具 schemas to strict mode
- Attach hidden attribution headers on verified native hosts only
- Keep OpenAI-only request shaping (`service_tier`, `store`, reasoning-compat, prompt-cache hints)


**Proxy/compatible routes:**
- Use looser compat behavior
- Strip Completions `store` from non-native `openai-completions` payloads
- Accept advanced `params.extra_body`/`params.extraBody`OpenAI pass-through JSON for OpenAI-compatible Completions proxies
- Accept `params.chat_template_kwargs`OpenAIOpenAI for OpenAI-compatible Completions proxies such as vLLM
- Do not force strict 工具 schemas or native-only headers


Azure OpenAI uses native transport and compat behavior but does not receive the hidden attribution headers.

相关

Section titled “相关”
Model selection

选择提供商、模型引用和故障转移行为。

Image generation

共享图像工具参数和提供商选择。

Video generation

共享视频工具参数和提供商选择。

OAuthOAuth and auth

认证详情和凭证重用规则。