Skip to main content

​
OpenAI

OpenAI 提供了 GPT 模型的开发者 API。Codex 支持 ChatGPT 登录 以获取订阅访问或 API 密钥 登录以按使用量计费。Codex 云端需要 ChatGPT 登录。OpenAI 明确支持在外部工具/工作流（如 OpenClaw）中使用订阅 OAuth。

​
选项 A：OpenAI API 密钥（OpenAI 平台）

适用场景： 直接使用 API 并按使用量计费。
从 OpenAI 控制台获取你的 API 密钥。

​
CLI 配置

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 模型文档中列出了用于直接调用 OpenAI API 的 gpt-5.4 和 gpt-5.4-pro 模型。OpenClaw 会通过 openai/* Responses 路径转发这两个模型。

​
选项 B：OpenAI Code (Codex) 订阅

适用场景： 使用 ChatGPT/Codex 订阅访问代替 API 密钥。
Codex 云端需要 ChatGPT 登录，Codex CLI 支持 ChatGPT 或 API 密钥登录。

​
CLI 配置（Codex OAuth）

# 在向导中运行 Codex OAuth
openclaw onboard --auth-choice openai-codex

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

​
配置示例（Codex 订阅）

{
  agents: { defaults: { model: { primary: "openai-codex/gpt-5.4" } } },
}
OpenAI 当前 Codex 文档中列出的当前 Codex 模型为 gpt-5.4。OpenClaw 将其映射为 openai-codex/gpt-5.4 用于 ChatGPT/Codex OAuth 访问。

​
传输默认设置

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 文档： 
{
  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 优先级处理

OpenAI 的 API 支持通过 service_tier=priority 来开启优先级处理。在 OpenClaw 中，设置 agents.defaults.models["openai/<model>"].params.serviceTier 可在直接使用 openai/* Responses 请求时传递该字段。 
{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.4": {
          params: {
            serviceTier: "priority",
          },
        },
      },
    },
  },
}
支持的取值包括 auto、default、flex 和 priority。

​
OpenAI Responses 服务器端压缩

对于直接的 OpenAI Responses 模型（使用 api: "openai-responses" 并且 baseUrl 指向 api.openai.com 的 openai/*），OpenClaw 现在默认启用 OpenAI 服务器端压缩 payload 提示：
  • 强制开启 store: true（除非模型兼容性设置了 supportsStore: false）
  • 注入 context_management: [{ type: "compaction", compact_threshold: ... }]
默认情况下，compact_threshold 是模型的 contextWindow 的 70%（若不可用则为 80000）。

​
显式启用服务器端压缩

当你需要强制注入 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。

​
注意事项