OpenAI

OpenClaw 使用同一个提供商 ID openai 来支持直接 API key 身份验证和 ChatGPT/Codex 订阅身份验证。openai/* 是规范的模型路由。 对于未设置运行时策略或策略为 auto 的嵌入式智能体轮次，OpenAI 的路由 事实决定 OpenClaw 是否可以隐式选择内置的 Codex app-server 运行时。 仅有 openai/* 前缀并不会选择运行时。

• 智能体模型 - openai/* 使用由显式 agentRuntime 配置或 OpenAI 的隐式路由策略选定的运行时。使用 Codex 身份验证登录，以使用 ChatGPT/Codex 订阅；如果需要基于密钥计费，则配置 API key 身份验证 配置文件。
• 非智能体 OpenAI API - 通过 OPENAI_API_KEY 或 openai API key 身份验证配置文件直接访问 OpenAI Platform，并按使用量计费。
• 旧版配置 - openclaw doctor --fix 会将旧 Codex 模型引用和配置文件 ID 修复为 openai/*。

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

使用量和成本跟踪

OpenClaw 将订阅配额与 Platform API 计费分开处理：

• ChatGPT/Codex OAuth 显示订阅方案、配额窗口和信用余额。
• OPENAI_ADMIN_KEY 会在 Control UI 的 使用量 中显示提供商报告的 30 天组织成本和补全使用量，包括每日支出、请求/令牌总数、热门模型和成本类别。
• OPENAI_PROJECT_ID 可选择将 Admin API 历史记录限定到一个项目。
• OpenClaw 绝不会将 OPENAI_API_KEY 或 openai 推理配置文件发送给组织 API；这些凭据可能属于自定义、Azure 或智能体本地端点。

显式 Admin key 的优先级高于 OAuth。提供商报告的历史记录不会与 OpenClaw 根据会话得出的估算成本合并；其中可能包含来自其他客户端的 API 活动和提供商侧的计费调整。

OpenAI 的 API 使用量仪表板文档介绍了访问使用量数据所需的组织所有者权限和显式 Usage Dashboard 权限。

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

快速选择

命名映射

隐式智能体运行时

当未设置提供商/模型 agentRuntime 策略或策略为 auto 时，OpenAI 由提供商所有的路由策略会根据有效端点和适配器选择隐式运行时：

显式的非默认提供商/模型 agentRuntime.id 仍具有最终决定权。 例如，agentRuntime.id: "openclaw" 会让原本符合 Codex 条件的路由继续使用 OpenClaw，而 agentRuntime.id: "codex" 则要求使用 Codex；如果有效路由未声明为 兼容 Codex，将以失败关闭方式处理。 运行时选择不会更改凭据类型或计费方式：Platform API key 身份验证与 ChatGPT/Codex 订阅身份验证仍然彼此独立。

openclaw doctor --fix 会将旧版 Codex 模型引用、旧版 Codex 身份验证 配置文件 ID 和旧版 Codex 身份验证顺序条目迁移到规范的 openai 路由。新身份验证顺序配置请使用 auth.order.openai。

GPT-5.6 有限预览

OpenClaw 可识别确切的 openai/gpt-5.6-sol、 openai/gpt-5.6-terra 和 openai/gpt-5.6-luna 模型 ID。在当前目录中， 这三个模型均提供 xhigh 和 max 推理级别。OpenAI 将 Sol 描述为 旗舰层级，将 Terra 描述为均衡层级，将 Luna 描述为速度更快、 成本更低的层级。请参阅 GPT-5.6 发布公告 和访问指南。

使用直接 OpenAI API key 身份验证时，不带后缀的 openai/gpt-5.6 ID 是 Sol 的别名，也是全新设置的默认值。原生 Codex 目录不会在客户端应用该直接 API 别名；根据工作区访问权限，它可能会显示确切的 Sol、Terra 和 Luna ID。 因此，全新的 ChatGPT/Codex OAuth 设置使用 openai/gpt-5.6-sol。 使用以下命令检查当前账户：

openclaw models list --provider openai

API 组织和 Codex 工作区的访问权限可能不同。如果 GPT-5.6 不可用， 请显式选择 GPT-5.5：

openclaw models set openai/gpt-5.5

OpenClaw 会显示上游访问错误，不会静默地将 GPT-5.6 选择替换为 GPT-5.5。

OpenClaw 功能覆盖范围

记忆嵌入

OpenClaw 可以使用 OpenAI 或兼容 OpenAI 的嵌入端点，为 memory_search 建立索引并生成查询嵌入：

{  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: "example-openai-key-not-real" },  agents: { defaults: { model: { primary: "openai/gpt-5.6" } } },}

{  env: { OPENAI_API_KEY: "example-openai-key-not-real" },  agents: { defaults: { model: { primary: "openai/chat-latest" } } },}

openclaw onboard --auth-choice openai

openclaw models auth login --provider openai

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

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

openclaw models list --provider openai

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

{  plugins: { entries: { codex: { enabled: true } } },  agents: {    defaults: {      model: { primary: "openai/gpt-5.6-sol" },    },  },  auth: {    order: {      openai: [        "openai:user@example.com",        "openai:api-key-backup",      ],    },  },}

openclaw models statusopenclaw models auth list --provider openaiopenclaw 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

openclaw doctor --fixopenclaw config validate

openclaw models auth login --provider openaiopenclaw models status --probe --probe-provider openai

openclaw models auth login --provider openai --profile-id openai:ritsukoopenclaw models auth login --provider openai --profile-id openai:lain

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

原生 Codex app-server 身份验证

当符合条件的精确官方 HTTPS 路由隐式选择原生 Codex app-server harness，或提供商/模型的 agentRuntime.id: "codex" 显式选择它时，该 harness 使用 openai/* 模型引用。其身份验证仍以账户为基础。OpenClaw 按以下顺序选择身份验证方式：

1. 智能体的有序 OpenAI 身份验证配置文件，最好位于 auth.order.openai 下。运行 openclaw doctor --fix 以迁移较旧的旧版 Codex 身份验证配置文件 ID 和身份验证顺序。
2. app-server 的现有账户，例如本地 Codex CLI ChatGPT 登录。对于默认的隔离智能体主目录，OpenClaw 会通过登录 RPC 将该原生 CLI 账户桥接到 app-server；它不会共享 CLI 的配置、插件或线程存储。
3. 仅对于本地 stdio app-server 启动，且仅当 app-server 报告没有账户时：先使用 CODEX_API_KEY，再使用 OPENAI_API_KEY。

本地 ChatGPT/Codex 订阅登录不会仅因为 Gateway 网关进程还为直接 OpenAI 模型或嵌入配置了 OPENAI_API_KEY 而被替换。环境变量 API 密钥回退仅适用于本地 stdio 无账户路径；它绝不会通过 WebSocket app-server 连接发送。选择订阅型 Codex 配置文件后，OpenClaw 还会阻止生成的 stdio app-server 子进程获取 CODEX_API_KEY 和 OPENAI_API_KEY，改为通过 app-server 登录 RPC 发送所选凭据。

当该订阅配置文件因 Codex 使用量限制而被阻止时，OpenClaw 会将此配置文件标记为阻止状态，直到 Codex 公布的重置时间，并允许身份验证顺序轮换到下一个 openai:* 配置文件，而不更改所选模型或退出 Codex harness。重置时间到达后，该订阅配置文件将重新可用。

图像生成

内置 openai 插件通过 image_generate 工具注册图像生成。它通过同一个 openai/gpt-image-2 模型引用支持 OpenAI API 密钥和 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/gpt-image-2 透明背景请求重写为 gpt-image-1.5，保护公共 OpenAI 和 OpenAI Codex OAuth 路由；Azure 和自定义 OpenAI 兼容端点会保留其已配置的部署/模型名称。

无头 CLI 运行也提供相同设置：

openclaw infer image generate \  --model openai/gpt-image-1.5 \  --output-format png \  --background transparent \  --prompt "透明背景上的简洁红色圆形贴纸" \  --json

从输入文件开始时，请将相同的 --output-format 和 --background 标志用于 openclaw infer image edit。--openai-background 仍可用作 OpenAI 专用别名。使用 --quality low|medium|high|auto 控制 OpenAI Images 的质量和成本。使用 --openai-moderation low|auto 从 image generate 或 image edit 传递 OpenAI 的审核提示。

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

生成：

/tool image_generate model=openai/gpt-image-2 prompt="为 macOS 上的 OpenClaw 制作一张精美的发布海报" size=3840x2160 count=1

生成透明 PNG：

/tool image_generate model=openai/gpt-image-1.5 prompt="透明背景上的简洁红色圆形贴纸" outputFormat=png background=transparent

编辑：

/tool image_generate model=openai/gpt-image-2 prompt="保留物体形状，将材质更改为半透明玻璃" image=/path/to/reference.png size=1024x1536

视频生成

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

OpenAI 图生视频请求使用 POST /v1/videos，并通过图像 input_reference 提交。单视频编辑使用 POST /v1/videos/edits，并将上传的视频放入 video 字段。

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

GPT-5 提示词贡献

OpenClaw 会为 openai 提供商上的 GPT-5 系列模型添加共享的 GPT-5 提示词贡献 （包括修复前的旧版 Codex 引用，它们会规范化为 openai/*）。其他同样提供 GPT-5 系列模型 ID 的提供商（例如 OpenRouter 或 opencode 路由）不会收到此叠加层； 它由提供商 ID openai 控制，而不是仅由模型 ID 控制。较旧的 GPT-4.x 模型绝不会 收到此叠加层。

原生 Codex app-server harness 不会通过开发者指令接收角色设定/工具纪律行为契约 或友好的交互风格叠加层；原生 Codex 会保留由 Codex 所有的基础行为、模型行为和 项目文档行为，并且 OpenClaw 会为原生线程禁用 Codex 的内置个性，使 Agent 工作区 中的个性文件保持权威。OpenClaw 仅向原生 Codex 线程贡献运行时上下文：渠道投递、 OpenClaw 动态工具、ACP 委派、工作区上下文和 OpenClaw Skills。来自同一贡献的 Heartbeat 指导文本是唯一例外：原生 Codex 的 Heartbeat 轮次确实会收到它，但它会 作为专用协作指令注入，而不是通过共享提示词贡献钩子注入。

GPT-5 贡献会为匹配的 OpenClaw 组装提示词添加带标签的行为契约，涵盖角色设定持久性、 执行安全、工具纪律、输出形式、完成检查和验证。渠道特定的回复和静默消息行为仍由 共享的 OpenClaw 系统提示词和出站投递策略负责。友好的交互风格层相互独立且可配置。

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

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

语音与话音

{  messages: {    tts: {      providers: {        openai: { model: "gpt-4o-mini-tts", speakerVoice: "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 密钥（而不是 OpenAI Platform 密钥）：

{  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 图像生成调用使用默认的 600s 请求超时。 每次调用的 timeoutMs 值仍会覆盖此默认值。

其他基础 URL（公共 OpenAI、OpenAI 兼容代理）继续使用标准 OpenAI 图像请求格式。

API 版本

设置 AZURE_OPENAI_API_VERSION，可为 Azure 图像生成路径固定特定的 Azure 预览版或正式发布版：

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

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

模型名称即部署名称

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

如果你创建了名为 gpt-image-2-prod、用于提供 gpt-image-2 的部署：

/tool image_generate model=openai/gpt-image-2-prod prompt="简洁的海报" size=1024x1024 count=1

相同的部署名称规则适用于通过内置 openai 提供商路由的任何图像生成调用。

区域可用性

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

参数差异

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

高级配置

以下每个模型的 params 示例会决定 OpenClaw 嵌入式提供商请求的格式。 配置这些参数属于显式编写请求行为，因此原本符合条件的 auto 路由仍会留在 OpenClaw 上，而不会隐式选择 Codex。原生 Codex app-server harness 自行管理 传输和请求设置；当有效路由未声明为与 Codex 兼容时，显式设置 agentRuntime.id: "codex" 会以关闭方式失败。

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

{  agents: {    defaults: {      models: {        "openai/gpt-5.5": { params: { fastMode: "auto", fastAutoOnSeconds: 30 } },      },    },  },}

{  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: {      embeddedAgent: { executionContract: "default" },    },  },}

相关内容