OpenAI

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

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

• 智能体模型 - 通过 Codex 运行时使用 openai/* 模型；若使用 ChatGPT/Codex 订阅，请用 openai-codex 凭证登录，或者在你有意使用 API key 凭证时配置 openai-codex 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/* 模型引用和 openai-codex 凭证配置文件。openclaw doctor --fix 会将旧版 openai-codex/* 模型引用重写为规范 OpenAI 模型路由。

# 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: "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" },
      agentRuntime: { id: "codex" },
    },
  },
}

openclaw models status
openclaw models auth list --provider openai-codex
openclaw config get agents.defaults.model --json
openclaw config get agents.defaults.agentRuntime --json

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

openclaw doctor --fix
openclaw config validate

openclaw models auth login --provider openai-codex
openclaw 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/* 模型引用加省略的运行时配置，或使用 agentRuntime.id: "codex"，但其凭证仍基于账户。OpenClaw 按以下顺序选择凭证：

1. 绑定到智能体的显式 OpenClaw openai-codex 凭证 profile。
2. app-server 的现有账户，例如本地 Codex CLI ChatGPT 登录。
3. 仅对于本地 stdio app-server 启动，当 app-server 报告没有账户且仍需要 OpenAI 凭证时，使用 CODEX_API_KEY，然后使用 OPENAI_API_KEY。

这意味着，仅仅因为 Gateway 网关进程也有用于直接 OpenAI 模型或嵌入的 OPENAI_API_KEY，本地 ChatGPT/Codex 订阅登录不会被替换。环境变量 API key 回退仅适用于本地 stdio 无账户路径；它不会被发送到 WebSocket app-server 连接。当选择订阅式 Codex profile 时，OpenClaw 还会将 CODEX_API_KEY 和 OPENAI_API_KEY 排除在派生的 stdio app-server 子进程之外，并通过 app-server 登录 RPC 发送所选凭据。

# 图像生成

内置 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"。

对于透明背景请求，智能体应调用 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 "A simple red circle sticker on a transparent background" \
  --json

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

对于 Codex OAuth 安装，保持同一个 openai/gpt-image-2 引用。当配置了 openai-codex OAuth profile 时，OpenClaw 会解析该存储的 OAuth 访问令牌，并通过 Codex Responses backend 发送图像请求。对于该请求，它不会先尝试 OPENAI_API_KEY，也不会静默回退到 API key。如果你想使用直接 OpenAI Images API 路由，请显式配置 models.providers.openai，并设置 API key、自定义 base URL 或 Azure 端点。 如果该自定义图像端点位于受信任的局域网/私有地址，还需设置 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 覆盖层，因此通过 agentRuntime.id: "codex" 强制使用的 openai/gpt-5.x 会话，即使 Codex 拥有其余 harness 提示词，也会保持相同的跟进和主动 Heartbeat 指导。

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 提供商路由的 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 提供商路由的图像生成调用。

# 区域可用性

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

// Disable warm-up
{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.5": {
          params: { openaiWsWarmup: false },
        },
      },
    },
  },
}

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

# 相关