OpenAI
OpenAI 提供业界领先的 GPT 模型系列。在 OpenClaw 中，您可以通过 API 密钥（OpenAI 平台）或 Codex 订阅（ChatGPT 登录）两种方式使用 OpenAI 模型。
OpenAI 明确支持在外部工具和工作流（如 OpenClaw）中使用 Codex 订阅 OAuth。
认证方式
OpenAI API 密钥（OpenAI 平台）
适用于直接使用 API 并按使用量计费的场景。获取 API 密钥
前往 OpenAI 控制台 创建您的 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 Codex（ChatGPT 登录）
适用于使用 ChatGPT/Codex 订阅访问代替 API 密钥的场景。配置步骤
启动 OAuth 流程
# 在引导配置中选择 Codex
openclaw onboard --auth-choice openai-codex
# 或直接运行 OAuth
openclaw models auth login --provider openai-codex
完成浏览器登录
按照提示在浏览器中完成 ChatGPT 登录流程。
设置默认模型
{
"agents": {
"defaults": {
"model": {
"primary": "openai-codex/gpt-5.4"
}
}
}
}
可用模型
OpenAI 平台模型（API 密钥）
使用 openai/* 前缀引用：
openai/gpt-5.4 - 最新旗舰模型openai/gpt-5.4-pro - 专业版模型
{
"agents": {
"defaults": {
"model": {
"primary": "openai/gpt-5.4"
}
}
}
}
Codex 模型（订阅访问）
使用 openai-codex/* 前缀引用：
openai-codex/gpt-5.4 - Codex 订阅模型
{
"agents": {
"defaults": {
"model": {
"primary": "openai-codex/gpt-5.4"
}
}
}
}
高级功能
传输方式配置
OpenClaw 使用 pi-ai 进行模型流式传输。对于 OpenAI 模型，默认传输方式为 "auto"（优先 WebSocket，失败后降级到 SSE）。
自动选择（推荐）
强制 WebSocket
强制 SSE
{
"agents": {
"defaults": {
"models": {
"openai/gpt-5.4": {
"params": {
"transport": "auto"
}
}
}
}
}
}
{
"agents": {
"defaults": {
"models": {
"openai/gpt-5.4": {
"params": {
"transport": "websocket"
}
}
}
}
}
}
{
"agents": {
"defaults": {
"models": {
"openai/gpt-5.4": {
"params": {
"transport": "sse"
}
}
}
}
}
}
"auto" - 自动选择（默认）"websocket" - 强制使用 WebSocket"sse" - 强制使用 Server-Sent Events
相关文档：
WebSocket 预热
OpenAI 文档中描述的预热功能是可选的。OpenClaw 对 openai/* 模型默认启用此功能，以降低使用 WebSocket 传输时的首次响应延迟。
{
"agents": {
"defaults": {
"models": {
"openai/gpt-5.4": {
"params": {
"openaiWsWarmup": true
}
}
}
}
}
}
{
"agents": {
"defaults": {
"models": {
"openai/gpt-5.4": {
"params": {
"openaiWsWarmup": false
}
}
}
}
}
}
优先级处理
OpenAI 的 API 支持通过 service_tier=priority 开启优先级处理。在 OpenClaw 中，设置 serviceTier 参数即可启用。
{
"agents": {
"defaults": {
"models": {
"openai/gpt-5.4": {
"params": {
"serviceTier": "priority"
}
}
}
}
}
}
auto - 自动选择default - 默认等级flex - 灵活等级priority - 优先级等级
服务器端压缩
对于直接的 OpenAI Responses 模型，OpenClaw 默认启用服务器端压缩以优化性能。
{
"agents": {
"defaults": {
"models": {
"openai/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
}
}
}
}
}
}
API 密钥轮换
OpenClaw 支持配置多个 OpenAI API 密钥，在遇到速率限制时自动轮换：
export OPENAI_API_KEYS="sk-key1,sk-key2,sk-key3"
密钥轮换仅在收到速率限制响应（如 429 错误）时触发。其他类型的错误会立即失败。
完整配置示例
{
"env": {
"OPENAI_API_KEY": "sk-..."
},
"agents": {
"defaults": {
"model": {
"primary": "openai/gpt-5.4"
}
}
}
}
故障排除
API 密钥无效
问题： 收到 401 Unauthorized 错误。
解决方案：
- 验证 API 密钥是否正确设置：
- 检查 API 密钥是否仍然有效（未被撤销）
- 重新生成 API 密钥并更新配置
速率限制错误
问题： 收到 429 Too Many Requests 错误。
解决方案：
- 配置多个 API 密钥实现自动轮换
- 升级您的 OpenAI 账户计划
- 实现请求速率控制
WebSocket 连接失败
问题： WebSocket 传输无法建立连接。
解决方案：
- 使用
transport: "auto" 自动降级到 SSE
- 或显式设置
transport: "sse" 强制使用 SSE
- 检查网络防火墙设置是否允许 WebSocket 连接
Codex OAuth 失败
问题： OAuth 登录流程失败。
解决方案：
- 确保浏览器可以正常访问 OpenAI
- 检查是否有代理或防火墙阻止 OAuth 回调
- 重新运行 OAuth 流程：
openclaw models auth login --provider openai-codex
相关资源
