OpenAI

OpenAI 为 GPT 模型提供开发者 API，Codex 也可通过 OpenAI 的 Codex 客户端作为 ChatGPT 计划中的编码智能体使用。OpenClaw 将这些接入面保持分离，让配置保持可预测。

OpenClaw 使用 openai/* 作为规范的 OpenAI 模型路由。OpenAI 模型上的嵌入式智能体 轮次默认通过原生 Codex 应用服务器运行时执行；直接的 OpenAI API key 凭证仍可用于图像、嵌入、语音和 realtime 等非智能体 OpenAI 接入面。

• 智能体模型 - 通过 Codex 运行时使用 openai/* 模型；如果要使用 ChatGPT/Codex 订阅，请用 Codex 凭证登录；如果你有意使用 API key 凭证，请配置一个兼容 Codex 的 OpenAI API key 备用项。
• 非智能体 OpenAI API - 通过 OPENAI_API_KEY 或 OpenAI API key 新手引导，直接访问 OpenAI Platform，并按用量计费。
• 旧版配置 - openai-codex/* 模型引用会由 openclaw doctor --fix 修复为 openai/* 加 Codex 运行时。

OpenAI 明确支持在 OpenClaw 这类外部工具和工作流中使用订阅 OAuth。

提供商、模型、运行时和渠道是彼此独立的层。如果这些标签混在一起，请先阅读 Agent Runtimes，再更改配置。

快速选择

命名映射

这些名称相似，但不能互换：

这意味着配置可以有意包含 openai/* 模型引用，同时凭证配置文件仍指向兼容 Codex 的凭据。新配置优先使用 auth.order.openai；现有 openai-codex:* 配置文件和 auth.order.openai-codex 仍受支持。openclaw doctor --fix 会将旧版 openai-codex/* 模型引用重写为规范 OpenAI 模型路由。

OpenClaw 功能覆盖

记忆嵌入

OpenClaw 可以为 memory_search 索引和查询嵌入使用 OpenAI，或兼容 OpenAI 的嵌入端点：

{  agents: {    defaults: {      memorySearch: {        provider: "openai",        model: "text-embedding-3-small",      },    },  },}

对于需要非对称嵌入标签的兼容 OpenAI 端点，请在 memorySearch 下设置 queryInputType 和 documentInputType。OpenClaw 会将它们作为提供商特定的 input_type 请求字段转发：查询嵌入使用 queryInputType；已索引的记忆分块和批量索引使用 documentInputType。完整示例见 记忆配置参考。

入门指南

选择你偏好的凭证方式，并按照设置步骤操作。

openclaw onboard --auth-choice openai-api-key

openclaw onboard --openai-api-key "$OPENAI_API_KEY"

openclaw models list --provider openai

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

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

openclaw onboard --auth-choice openai-codex

openclaw models auth login --provider openai-codex

openclaw models auth login --provider openai-codex --device-code

openclaw config set agents.defaults.model.primary openai/gpt-5.5

openclaw models list --provider openai-codex

{  plugins: { entries: { codex: { enabled: true } } },  agents: {    defaults: {      model: { primary: "openai/gpt-5.5" },    },  },}

{  plugins: { entries: { codex: { enabled: true } } },  agents: {    defaults: {      model: { primary: "openai/gpt-5.5" },    },  },  auth: {    order: {      openai: [        "openai-codex:[email protected]",        "openai:api-key-backup",      ],    },  },}

openclaw models statusopenclaw models auth list --provider openai-codexopenclaw config get agents.defaults.model --jsonopenclaw config get models.providers.openai.agentRuntime --json

openclaw models status --agent <id>openclaw models auth list --agent <id> --provider openai-codex

openclaw doctor --fixopenclaw config validate

openclaw models auth login --provider openai-codexopenclaw models status --probe --probe-provider openai-codex

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

原生 Codex app-server 凭证

原生 Codex app-server harness 使用 openai/* 模型 ref 加省略的运行时配置，或提供商/模型 agentRuntime.id: "codex"，但其凭证仍基于账号。OpenClaw 按以下顺序选择凭证：

1. 智能体的有序 OpenAI 凭证配置文件，最好放在 auth.order.openai 下。现有 openai-codex:* 配置文件和 auth.order.openai-codex 对较旧安装仍然有效。
2. app-server 的现有账号，例如本地 Codex CLI ChatGPT 登录。
3. 仅对于本地 stdio app-server 启动，当 app-server 报告没有账号且仍需要 OpenAI 凭证时，依次使用 CODEX_API_KEY，然后 OPENAI_API_KEY。

这意味着本地 ChatGPT/Codex 订阅登录不会仅因为 Gateway 网关进程同时拥有用于直接 OpenAI 模型或嵌入的 OPENAI_API_KEY 就被替换。环境 API-key fallback 仅用于本地 stdio 无账号路径；它不会发送到 WebSocket app-server 连接。选择订阅风格的 Codex 配置文件时，OpenClaw 还会避免将 CODEX_API_KEY 和 OPENAI_API_KEY 放入派生的 stdio app-server 子进程，并通过 app-server login RPC 发送选定凭证。当该订阅配置文件被 Codex 用量限制阻止时，OpenClaw 可以轮换到下一个有序的 openai:* API-key 配置文件，而无需更改选定模型或退出 Codex harness。订阅重置时间经过后，该订阅配置文件会再次可用。

图像生成

内置 openai 插件通过 image_generate 工具注册图像生成。 它通过相同的 openai/gpt-image-2 模型 ref 同时支持 OpenAI API-key 图像生成和 Codex OAuth 图像生成。

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

gpt-image-2 是 OpenAI 文本生成图像和图像编辑的默认值。gpt-image-1.5、gpt-image-1 和 gpt-image-1-mini 仍可作为显式模型覆盖使用。对于透明背景 PNG/WebP 输出，请使用 openai/gpt-image-1.5；当前 gpt-image-2 API 会拒绝 background: "transparent"。

对于透明背景请求，智能体应调用 image_generate，并设置 model: "openai/gpt-image-1.5"、outputFormat: "png" 或 "webp"，以及 background: "transparent"；较旧的 openai.background 提供商选项仍被接受。OpenClaw 还会保护公共 OpenAI 和 OpenAI Codex OAuth 路由，将默认的 openai/gpt-image-2 透明请求重写为 gpt-image-1.5；Azure 和自定义 OpenAI 兼容端点会保留其配置的部署/模型名称。

同一设置也暴露给无头 CLI 运行：

openclaw infer image generate \  --model openai/gpt-image-1.5 \  --output-format png \  --background transparent \  --prompt "A simple red circle sticker on a transparent background" \  --json

从输入文件开始时，将相同的 --output-format 和 --background 标志用于 openclaw infer image edit。 --openai-background 仍可作为 OpenAI 专用别名使用。

对于 Codex OAuth 安装，保持相同的 openai/gpt-image-2 ref。配置 openai-codex OAuth 配置文件后，OpenClaw 会解析该存储的 OAuth 访问令牌，并通过 Codex Responses 后端发送图像请求。它不会先尝试 OPENAI_API_KEY，也不会对该请求静默回退到 API key。当你想改用直接 OpenAI Images API 路由时，请使用 API key、自定义基础 URL 或 Azure 端点显式配置 models.providers.openai。 如果该自定义图像端点位于受信任的 LAN/私有地址，还要设置 browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true；除非存在此显式选择加入，OpenClaw 会继续阻止私有/内部 OpenAI 兼容图像端点。

生成：

/tool image_generate model=openai/gpt-image-2 prompt="A polished launch poster for OpenClaw on macOS" size=3840x2160 count=1

生成透明 PNG：

/tool image_generate model=openai/gpt-image-1.5 prompt="A simple red circle sticker on a transparent background" outputFormat=png background=transparent

编辑：

/tool image_generate model=openai/gpt-image-2 prompt="Preserve the object shape, change the material to translucent glass" image=/path/to/reference.png size=1024x1536

视频生成

内置 openai 插件通过 video_generate 工具注册视频生成。

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

GPT-5 提示词贡献

OpenClaw 为跨提供商的 GPT-5 系列运行添加共享的 GPT-5 提示词贡献。它按模型 id 应用，因此 openai/gpt-5.5、旧版修复前引用（例如 openai-codex/gpt-5.5）、openrouter/openai/gpt-5.5、opencode/gpt-5.5 以及其他兼容的 GPT-5 引用都会收到相同覆盖层。较旧的 GPT-4.x 模型不会收到。

内置的原生 Codex harness 通过 Codex app-server 开发者指令使用相同的 GPT-5 行为和 Heartbeat 覆盖层，因此通过 Codex 路由的 openai/gpt-5.x 会话会保留相同的跟进和主动 Heartbeat 指引，尽管 Codex 拥有 harness 提示词的其余部分。

GPT-5 贡献会为人格持续性、执行安全、工具纪律、输出形态、完成检查和验证添加带标签的行为契约。特定渠道的回复和静默消息行为保留在共享的 OpenClaw 系统提示词和出站投递策略中。GPT-5 指引始终对匹配模型启用。友好的交互风格层是独立的，并且可配置。

{  agents: {    defaults: {      promptOverlays: {        gpt5: { personality: "friendly" },      },    },  },}

openclaw config set agents.defaults.promptOverlays.gpt5.personality off

语音与音频

{  messages: {    tts: {      providers: {        openai: { model: "gpt-4o-mini-tts", voice: "coral" },      },    },  },}

{  tools: {    media: {      audio: {        models: [          {            type: "provider",            provider: "openai",            model: "gpt-4o-transcribe",          },        ],      },    },  },}

Azure OpenAI 端点

内置的 openai 提供商可以通过覆盖基础 URL，将图像 生成指向 Azure OpenAI 资源。在图像生成路径上，OpenClaw 会检测 models.providers.openai.baseUrl 上的 Azure 主机名，并自动切换到 Azure 的请求形态。

在以下情况使用 Azure OpenAI：

• 你已经拥有 Azure OpenAI 订阅、配额或企业协议
• 你需要 Azure 提供的区域数据驻留或合规控制
• 你希望将流量保留在现有 Azure 租户内

配置

要通过内置 openai 提供商使用 Azure 图像生成，请将 models.providers.openai.baseUrl 指向你的 Azure 资源，并将 apiKey 设置为 Azure OpenAI key（不是 OpenAI Platform key）：

{  models: {    providers: {      openai: {        baseUrl: "https://<your-resource>.openai.azure.com",        apiKey: "<azure-openai-api-key>",      },    },  },}

OpenClaw 会识别以下 Azure 主机后缀，用于 Azure 图像生成 路由：

• *.openai.azure.com
• *.services.ai.azure.com
• *.cognitiveservices.azure.com

对于已识别 Azure 主机上的图像生成请求，OpenClaw 会：

• 发送 api-key 标头，而不是 Authorization: Bearer
• 使用部署作用域路径（/openai/deployments/{deployment}/...）
• 在每个请求后追加 ?api-version=...
• 对 Azure 图像生成调用使用 600 秒默认请求超时。 每次调用的 timeoutMs 值仍会覆盖此默认值。

其他基础 URL（公共 OpenAI、OpenAI 兼容代理）会保留标准 OpenAI 图像请求形态。

API 版本

设置 AZURE_OPENAI_API_VERSION，为 Azure 图像生成路径固定特定的 Azure 预览版或 GA 版本：

export AZURE_OPENAI_API_VERSION="2024-12-01-preview"

未设置该变量时，默认值为 2024-12-01-preview。

模型名称是部署名称

Azure OpenAI 会将模型绑定到部署。对于通过内置 openai provider 路由的 Azure 图像生成请求，OpenClaw 中的 model 字段必须是你在 Azure 门户中配置的 Azure 部署名称，而不是公开的 OpenAI 模型 ID。

如果你创建了一个名为 gpt-image-2-prod、提供 gpt-image-2 服务的部署：

/tool image_generate model=openai/gpt-image-2-prod prompt="A clean poster" size=1024x1024 count=1

同样的部署名称规则也适用于通过内置 openai provider 路由的图像生成调用。

区域可用性

Azure 图像生成目前仅在部分区域可用（例如 eastus2、swedencentral、polandcentral、westus3、uaenorth）。创建部署前，请查看 Microsoft 当前的区域列表，并确认你的区域提供了特定模型。

参数差异

Azure OpenAI 和公开 OpenAI 并不总是接受相同的图像参数。Azure 可能会拒绝公开 OpenAI 允许的选项（例如 gpt-image-2 上的某些 background 值），或仅在特定模型版本上公开这些选项。这些差异来自 Azure 和底层模型，而不是 OpenClaw。如果 Azure 请求因验证错误而失败，请在 Azure 门户中查看你的特定部署和 API 版本支持的参数集。

高级配置

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

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

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

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

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

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

{  agents: {    defaults: {      embeddedPi: { executionContract: "strict-agentic" },    },  },}

相关内容