OpenAI

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

• 智能体模型 - 通过显式 agentRuntime 配置或 OpenAI 的隐式路由策略所选的运行时使用 openai/*。 若要使用 ChatGPT/Codex 订阅，请通过 Codex 身份验证登录；若要按密钥计费，请配置 API 密钥身份验证 配置文件。
• 非智能体 OpenAI API - 通过 OPENAI_API_KEY 或 openai API 密钥身份验证配置文件 直接访问 OpenAI Platform，并按使用量计费。
• 旧版配置 - openclaw doctor --fix 会将 codex/* 和 openai-codex/* 引用修复为 openai/*，并添加模型范围的 agentRuntime.id: "codex"。

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 密钥的优先级高于 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 密钥 身份验证与 ChatGPT/Codex 订阅身份验证仍然彼此独立。

openclaw doctor --fix 会将旧版 codex/* 和 openai-codex/* 模型 引用、旧版 Codex 身份验证配置文件 ID，以及旧版 Codex 身份验证顺序条目迁移到 规范 openai 路由。迁移后的模型引用会获得模型范围的 agentRuntime.id: "codex"；新的身份验证顺序配置请使用 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 密钥身份验证时，不带限定的 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 索引和查询生成嵌入：

{  memory: {    search: {      provider: "openai",      model: "text-embedding-3-small",    },  },}

对于需要非对称嵌入标签的兼容 OpenAI 端点，请在 memory.search 下设置 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.6-terra",            name: "GPT-5.6 Terra",            contextWindow: 1050000,            contextTokens: 922000,            maxTokens: 128000,          },        ],      },    },  },  agents: {    defaults: {      model: { primary: "openai/gpt-5.6-terra" },      models: {        "openai/gpt-5.6-terra": {          agentRuntime: { id: "openclaw" },          params: {            responsesServerCompaction: true,            responsesCompactThreshold: 700000,          },        },      },    },  },}

原生 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。

即使 Gateway 网关进程还为直接 OpenAI 模型或嵌入设置了 OPENAI_API_KEY，也不会因此替换本地 ChatGPT/Codex 订阅登录。环境变量 API key 回退仅适用于本地 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 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 仍可用作显式模型覆盖。使用 openai/gpt-image-1.5 可获得透明背景的 PNG/WebP 输出；当前 gpt-image-2 API 会拒绝 background: "transparent"。

对于透明背景请求，请使用 model: "openai/gpt-image-1.5"、outputFormat: "png" 或 "webp"，以及 background: "transparent" 调用 image_generate；较旧的 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

从输入文件开始时，请对 openclaw infer image edit 使用相同的 --output-format 和 --background 标志。--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 key。 如果要改用直接调用 OpenAI Images API 的路径，请通过 API key、自定义基础 URL 或 Azure 端点显式配置 models.providers.openai。如果该自定义图像端点位于受信任的局域网/私有地址， 还需设置 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 提示词贡献（包括规范化为 openai/* 的修复前旧版 Codex 引用）。 其他同样提供 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 轮次确实会收到该文本，它会作为专用协作指令注入，而不是通过共享的 提示词贡献钩子注入。

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

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

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

语音与语音处理

{  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 图像生成调用使用默认的 600 秒请求超时。 每次调用的 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 应用服务器 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" },    },  },}

相关内容