OpenAI

OpenAI

OpenAI 为 GPT 模型提供开发者 API。Codex 支持通过 ChatGPT 登录 进行订阅访问，或通过 API 密钥 登录进行按量付费访问。Codex 云端需要 ChatGPT 登录。 OpenAI 明确支持在外部工具/工作流（如 OpenClaw）中使用订阅 OAuth。

选项 A：OpenAI API 密钥 (OpenAI Platform)

最适用于： 直接 API 访问和按使用量计费。 从 OpenAI 仪表板获取您的 API 密钥。

CLI 设置

openclaw onboard --auth-choice openai-api-key
# or non-interactive
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 API 使用。OpenClaw 通过 openai/* Responses 路径转发两者。 OpenClaw 故意抑制了过时的 openai/gpt-5.3-codex-spark 行， 因为直接的 OpenAI API 调用会在实时流量中拒绝它。

OpenClaw 不在直接的 OpenAI API 路径上暴露 openai/gpt-5.3-codex-spark。pi-ai 仍然为该模型内置了一行，但实时的 OpenAI API 请求目前会拒绝它。Spark 在 OpenClaw 中被视为仅限 Codex 使用。

选项 B：OpenAI Code (Codex) 订阅

最适合： 使用 ChatGPT/Codex 订阅访问而不是 API 密钥。 Codex cloud 需要 ChatGPT 登录，而 Codex CLI 支持 ChatGPT 或 API 密钥登录。

CLI 设置 (Codex OAuth)

# Run Codex OAuth in the wizard
openclaw onboard --auth-choice openai-codex

# Or run OAuth directly
openclaw models auth login --provider openai-codex

配置代码段 (Codex 订阅)

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

OpenAI 当前的 Codex 文档将 gpt-5.4 列为当前的 Codex 模型。OpenClaw 将其映射到 openai-codex/gpt-5.4 以供 ChatGPT/Codex OAuth 使用。

如果您的 Codex 账户有权使用 Codex Spark，OpenClaw 也支持：

• openai-codex/gpt-5.3-codex-spark

OpenClaw 将 Codex Spark 视为仅限 Codex 使用。它不暴露直接的 openai/gpt-5.3-codex-spark API 密钥路径。

当 pi-ai 发现它时，OpenClaw 也会保留 openai-codex/gpt-5.3-codex-spark。请将其视为依赖授权且具有实验性功能：Codex Spark 与 GPT-5.4 /fast 是分开的，其可用性取决于登录的 Codex / ChatGPT 账户。

传输默认值

OpenClaw 使用 pi-ai 进行模型流式传输。对于 openai/* 和 openai-codex/*，默认传输方式为 "auto"（优先 WebSocket，然后是 SSE 回退）。

您可以设置 agents.defaults.models.<provider/model>.params.transport：

• "sse"：强制使用 SSE
• "websocket"：强制使用 WebSocket
• "auto"：尝试 WebSocket，然后回退到 SSE

对于 openai/* (Responses API)，当使用 WebSocket 传输时，OpenClaw 默认也会启用 WebSocket 预热（openaiWsWarmup: true）。

相关的 OpenAI 文档：

• 实时 API 与 WebSocket
• 流式 API 响应 (SSE)

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

OpenAI WebSocket 预热

OpenAI 文档将预热描述为可选。OpenClaw 默认为 openai/* 启用它，以减少使用 WebSocket 传输时的首轮延迟。

禁用预热

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

显式启用预热

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

OpenAI 和 Codex 优先处理

OpenAI 的 API 通过 service_tier=priority 暴露优先处理功能。在 OpenClaw 中，设置 agents.defaults.models["<provider>/<model>"].params.serviceTier 以便在原生 OpenAI/Codex Responses 端点上传递该字段。

{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.4": {
          params: {
            serviceTier: "priority",
          },
        },
        "openai-codex/gpt-5.4": {
          params: {
            serviceTier: "priority",
          },
        },
      },
    },
  },
}

支持的值为 auto、default、flex 和 priority。

OpenClaw 会将 params.serviceTier 转发给直接的 openai/* Responses 请求以及 openai-codex/* Codex Responses 请求，前提是这些模型指向 原生 OpenAI/Codex 端点。

重要行为：

• 直接的 openai/* 必须指向 api.openai.com
• openai-codex/* 必须指向 chatgpt.com/backend-api
• 如果您通过其他基础 URL 或代理路由任一提供商，OpenClaw 将保持 service_tier 不变

OpenAI 快速模式

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

• 聊天/UI：/fast status|on|off
• 配置：agents.defaults.models["<provider>/<model>"].params.fastMode

启用快速模式后，OpenClaw 会将其映射到 OpenAI 优先处理：

• 对 api.openai.com 的直接 openai/* Responses 调用会发送 service_tier = "priority"
• 对 chatgpt.com/backend-api 的 openai-codex/* Responses 调用也会发送 service_tier = "priority"
• 现有的有效负载 service_tier 值将保留
• 快速模式不会重写 reasoning 或 text.verbosity

示例：

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

会话覆盖优先于配置。在 Sessions UI 中清除会话覆盖 将会话返回到配置的默认值。

OpenAI Responses 服务器端压缩

对于直接的 OpenAI Responses 模型（openai/* 使用 api: "openai-responses" 搭配 baseUrl 在 api.openai.com 上），OpenClaw 现在会自动启用 OpenAI 服务器端 压缩负载提示：

• 强制 store: true（除非模型兼容性设置了 supportsStore: false）
• 注入 context_management: [{ type: "compaction", compact_threshold: ... }]

默认情况下，compact_threshold 是模型 contextWindow 的 70%（或不可用时使用 80000 ）。

显式启用服务器端压缩

当你想要在兼容的 Responses 模型上强制注入 context_management 时使用此选项（例如 Azure OpenAI Responses）：

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

使用自定义阈值启用

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

禁用服务器端压缩

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

responsesServerCompaction 仅控制 context_management 的注入。 直接的 OpenAI Responses 模型仍然会强制 store: true，除非兼容性设置了 supportsStore: false。

注意事项

• 模型引用始终使用 provider/model（请参阅 /concepts/models）。
• 身份验证详细信息 + 重用规则位于 /concepts/oauth。