OpenClaw OpenAI 接入教程，API Key 和 Codex 配置指南

OpenAI 是 OpenClaw 里最常见的模型提供商之一，但官方文档并不是把它简单写成“填个 API Key 就结束”。真正需要理解的是，OpenClaw 在 OpenAI 这里支持两条不同路线：

• OpenAI API Key：适合开发者 API、按量付费
• OpenAI Code（Codex）订阅：适合使用 ChatGPT / Codex 订阅登录

这两条路都是真的支持，但它们的认证方式、模型命名和适用场景并不一样。

先理解两种接入路线#

路线 A：OpenAI API Key

最适合：

• 你已经在 OpenAI Platform 开通 API
• 希望按调用量计费
• 希望配置最可控、最标准

路线 B：OpenAI Code（Codex）订阅

最适合：

• 你已经有 ChatGPT / Codex 订阅
• 希望通过 OAuth 登录，而不是单独管理 API Key
• 你明确要走 openai-codex/* 这条模型命名路线

官方文档明确说明，Codex 支持 ChatGPT 登录做订阅访问，Codex cloud 需要 ChatGPT 登录，而 OpenClaw 也明确支持把这种订阅 OAuth 用在外部工作流里。

什么时候优先选 API Key#

如果你只是想把 OpenClaw 稳稳接上 OpenAI，优先选 API Key。原因很简单：

• 配置最直观
• 排障边界更清楚
• 很多团队环境更容易做密钥管理
• 模型与提供商的对应关系更简单

一般只有在你明确知道自己要用 Codex 订阅路线时，才值得把初始接入建在 OAuth 上。

方式一：通过 OpenAI API Key 接入#

官方给出的 onboarding 命令是：

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"
      }
    }
  }
}

这段配置代表：

• 认证通过 env.OPENAI_API_KEY
• 默认主模型使用 openai/gpt-5.4

如果你想最小成本先跑通，先不要一上来就加太多模型别名、传输参数和 fallback，先确保这一版能稳定调用成功。

方式二：通过 OpenAI Code（Codex）订阅接入#

官方给出的向导命令是：

openclaw onboard --auth-choice openai-codex

如果你已经完成基本安装，也可以直接发起认证：

openclaw models auth login --provider openai-codex

这条路径适合已经明确要使用 Codex 订阅身份的用户，而不是想把 OpenAI API 当作通用计费接口的用户。

Codex 订阅路线的模型命名#

官方示例配置是：

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

这意味着：

• openai/gpt-5.4 属于直接 OpenAI API 路线
• openai-codex/gpt-5.4 属于 Codex OAuth 路线

这两个名字看着很像，但认证来源不是一回事。配置时不要混淆。

官方还提到，如果你的账户 entitlement 支持，也可能出现：

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

它被 OpenClaw 视为 Codex 专属实验路线，不会作为直接的 openai/* API Key 模型公开。

两条路线怎么选#

你可以用这条简单判断：

• 想稳定、标准、容易自动化：选 openai-api-key
• 已有 ChatGPT / Codex 订阅，而且明确想走 OAuth：选 openai-codex

如果你还没完全想清楚，就先用 API Key，把链路跑通后再考虑是否迁移到 Codex 订阅路线。

模型默认值应该怎么配#

对大多数用户，最稳的起点依然是：

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

如果你希望配置 fallback，可以后续再加。但我不建议在初次接入时同时叠：

• 多个 provider
• 多个 fallback
• 传输层参数
• 快速模式
• 服务等级

因为一旦调用异常，你会很难分辨问题到底来自认证、模型、路由还是参数。

配好以后先怎么验证#

建议至少跑下面几步：

openclaw models status
openclaw status --deep

验证目标是确认：

• OpenAI 认证状态是否正常
• 默认模型是否被识别
• Gateway 深度检查里是否能正确探测 provider

如果这一步都还没过，就不要急着去接消息渠道，否则会把问题混在一起。

高级项 1：Codex 路线的 transport#

官方给出的 Codex 订阅配置里，还展示了 transport: "auto"：

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

对多数用户来说，这个参数不需要一开始就手动改。只有当你已经知道自己在调整传输行为时，再去显式配置会更合适。

高级项 2：OpenAI WebSocket 预热#

官方文档提到，OpenClaw 对 openai/* 默认启用 WebSocket 预热，用来减少首个响应的延迟。

显式禁用

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

显式启用

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

如果你没有明确性能需求，一般不需要碰它。保留默认值通常更稳。

高级项 3：服务等级 serviceTier#

官方文档支持把 OpenAI 的 service_tier 透传给 openai/* Responses 请求：

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

支持的值包括：

• auto
• default
• flex
• priority

这不是初学者必须理解的第一层配置，但如果你在生产场景里关心响应等级和延迟策略，它会有价值。

高级项 4：快速模式 fastMode#

官方文档说明，openai/* 和 openai-codex/* 都支持快速模式。它本质上是一组低延迟偏好的组合开关。

你可以在会话里用：

/fast status
/fast on
/fast off

也可以在配置里打开：

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

官方说明，开启后 OpenClaw 会偏向低延迟参数，比如较低的 reasoning effort、较低的 verbosity，并在直接 OpenAI Responses 路径上使用更快的服务等级。

最常见的误区#

误区 1：openai/gpt-5.4 和 openai-codex/gpt-5.4 可以随便互换

不行。名字相似，但认证方式不同，背后的 provider 路线也不同。

误区 2：已经登录 ChatGPT，就不用再管 OpenAI API Key

只有当你明确走 openai-codex 订阅路线时才成立。如果你配置的是 openai/*，那就还是 API Key 逻辑。

误区 3：一开始就该上所有高级参数

不建议。最有效的策略仍然是：

1. 先把 API Key 或 OAuth 跑通
2. 确认默认模型能调用
3. 再按需补 serviceTier、fastMode、openaiWsWarmup

推荐的落地顺序#

对绝大多数用户，我建议：

1. 先用 API Key 跑通
2. 主模型先设成 openai/gpt-5.4
3. 用 openclaw models status 和 openclaw status --deep 验证
4. 需要更低延迟时，再考虑 fastMode
5. 已经明确依赖 ChatGPT / Codex 订阅时，再切到 openai-codex

OpenAI 在 OpenClaw 里并不难接，真正容易让人困惑的只有一件事：把 API Key 路线和 Codex 订阅路线混到一起。只要你一开始把这条边界分清，后面的配置就会顺很多。