本页介绍在 OpenClaw 中配置 OpenAI 的完整方法。支持两条路径：直接 API Key（按量计费）和 OpenAI Codex 订阅 OAuth（ChatGPT 登录）。覆盖当前模型 ID（gpt-5.4、gpt-5.4-pro）、WebSocket/SSE 传输选择、Fast Mode 优先处理、服务端上下文压缩（context_management）、图像生成（gpt-image-1）和视频生成（sora-2）配置。

OpenAI

OpenAI 提供 GPT 模型系列的开发者 API。在 OpenClaw 中，支持以下两种接入方式：

• Option A（OpenAI API Key）：直接按量计费访问
• Option B（Codex 订阅 OAuth）：通过 ChatGPT 登录使用订阅配额

OpenAI 明确支持在 OpenClaw 等外部工具中通过订阅 OAuth 使用 Codex。

默认交互风格

OpenClaw 为 openai/* 和 openai-codex/* 模型提供一个小型 OpenAI 专属 Prompt 叠加层，让助手更亲切、简洁，偶尔使用 Emoji。

配置键：plugins.entries.openai.config.personality

值	效果
"friendly"	默认，启用 OpenAI 专属叠加层
"off"	禁用叠加层，只使用 OpenClaw 基础 Prompt

openclaw config set plugins.entries.openai.config.personality off

Option A：OpenAI API Key

适合标准 API 访问和按量计费。

openclaw onboard --auth-choice openai-api-key
# 或非交互式
openclaw onboard --openai-api-key "$OPENAI_API_KEY"

配置示例：

{
  env: { OPENAI_API_KEY: "sk-..." },
  agents: { defaults: { model: { primary: "openai/gpt-5.4" } } },
}

当前 OpenAI API 模型：gpt-5.4、gpt-5.4-pro（均通过 openai/* Responses 路径转发）。

图像生成

OpenClaw 内置 OpenAI 图像生成，通过共享 image_generate 工具：

• 默认图像模型：openai/gpt-image-1
• 每次最多生成 4 张图像
• 支持编辑模式，最多 5 张参考图
• 支持 size 参数

当前限制：OpenClaw 不转发 aspectRatio 或 resolution 给 OpenAI Images API。

设置 OpenAI 为默认图像提供商：

{
  agents: {
    defaults: {
      imageGenerationModel: { primary: "openai/gpt-image-1" },
    },
  },
}

视频生成

OpenClaw 内置 OpenAI 视频生成，通过共享 video_generate 工具：

• 默认视频模型：openai/sora-2
• 支持文本转视频、图像转视频和单视频参考/编辑流程
• 当前限制：最多 1 张图像或 1 段视频参考输入
• 当前限制：只转发 size 参数，其他参数（aspectRatio、resolution、audio、watermark）会被忽略并返回警告

设置 OpenAI 为默认视频提供商：

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

Option B：Codex 订阅 OAuth

适合使用 ChatGPT/Codex 订阅，无需 API Key。

# 通过向导运行 Codex OAuth
openclaw onboard --auth-choice openai-codex

# 或直接运行 OAuth
openclaw models auth login --provider openai-codex

配置示例：

{
  agents: { defaults: { model: { primary: "openai-codex/gpt-5.4" } } },
}

Codex 上下文窗口限制

对于 openai-codex/gpt-5.4：

• 原生 contextWindow：1050000
• 默认运行时 contextTokens 上限：272000（延迟和质量综合最优）

自定义上限：

{
  models: {
    providers: {
      "openai-codex": {
        models: [{ id: "gpt-5.4", contextTokens: 160000 }],
      },
    },
  },
}

传输方式选择

默认传输："auto"（WebSocket 优先，失败后回退 SSE）。

{
  agents: {
    defaults: {
      models: {
        "openai-codex/gpt-5.4": {
          params: { transport: "auto" },
        },
      },
    },
  },
}

支持值："sse"、"websocket"、"auto"

openai/*（Responses API）还默认开启 WebSocket 预热（openaiWsWarmup: true）以降低首轮延迟。

Fast Mode（优先处理）

OpenClaw 的快速模式对 OpenAI 映射到 service_tier=priority：

{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.4": { params: { fastMode: true } },
        "openai-codex/gpt-5.4": { params: { fastMode: true } },
      },
    },
  },
}

也可在会话中用 /fast on 临时开启。支持的 serviceTier 值：auto、default、flex、priority。

注意：service_tier 只在目标为 api.openai.com 或 chatgpt.com/backend-api 时生效；通过代理或自定义 base URL 时不注入。

服务端上下文压缩

对于直接 OpenAI Responses 模型（api: "openai-responses"），OpenClaw 自动启用服务端上下文压缩：

• 强制 store: true
• 注入 context_management: [{ type: "compaction", compact_threshold: ... }]
• 默认 compact_threshold 为模型 contextWindow 的 70%

手动禁用：

{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.4": {
          params: { responsesServerCompaction: false },
        },
      },
    },
  },
}

自定义阈值：

{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.4": {
          params: {
            responsesServerCompaction: true,
            responsesCompactThreshold: 120000,
          },
        },
      },
    },
  },
}

原生路径 vs OpenAI 兼容路径

特性	原生（api.openai.com / chatgpt.com）	兼容（第三方 /v1 代理）
reasoning: { effort: "none" }	保留	默认行为
工具 schema 严格模式	默认启用	不强制
隐藏 attribution 请求头	附加	不附加
service_tier、store 等原生字段	支持	不注入

常见问题

Q: API Key 方式和 Codex 订阅 OAuth 有什么区别？

A: API Key 按实际 token 用量计费，账单透明可控，适合生产环境和高频使用。Codex 订阅 OAuth 消耗 ChatGPT 订阅配额，适合已有订阅且用量不大的场景。两者的模型 ID 前缀不同：API Key 用 openai/...，Codex 用 openai-codex/...。

Q: WebSocket 连接失败后会怎样？

A: 在 "auto" 传输模式下，OpenClaw 会先尝试重试一次 WebSocket，失败后自动回退到 SSE，同时在约 60 秒冷却期内后续请求直接走 SSE，避免反复切换。强制 "websocket" 模式则会直接报错。

Q: 服务端上下文压缩会影响我的对话内容吗？

A: 服务端压缩由 OpenAI 服务端执行，会在上下文接近阈值时自动归档早期对话。这可能导致模型遗忘早期内容。如果你需要保留完整上下文，可以设置 responsesServerCompaction: false 或提高 responsesCompactThreshold。