OpenAI

OpenAI proporciona API para desarrolladores para los modelos GPT, y Codex también está disponible como un agente de programación del plan ChatGPT mediante los clientes Codex de OpenAI. OpenClaw usa un único id. de proveedor, openai, para ambas formas de autenticación.

OpenClaw usa openai/* como la ruta canónica de modelos de OpenAI. Los turnos de agentes integrados en modelos de OpenAI se ejecutan mediante el runtime nativo del servidor de aplicaciones de Codex de forma predeterminada; la autenticación directa con clave de API de OpenAI sigue estando disponible para superficies de OpenAI que no son de agente, como imágenes, embeddings, voz y tiempo real.

• Modelos de agente - modelos openai/* mediante el runtime de Codex; inicia sesión con autenticación de Codex para usar una suscripción de ChatGPT/Codex, o configura una copia de seguridad de clave de API de OpenAI compatible con Codex cuando quieras intencionalmente autenticación con clave de API.
• API de OpenAI que no son de agente - acceso directo a OpenAI Platform con facturación basada en uso mediante OPENAI_API_KEY o incorporación con clave de API de OpenAI.
• Configuración heredada - las referencias de modelos Codex heredadas se reparan con openclaw doctor --fix a openai/* más el runtime de Codex.

OpenAI admite explícitamente el uso de OAuth de suscripción en herramientas externas y flujos de trabajo como OpenClaw.

Proveedor, modelo, runtime y canal son capas separadas. Si esas etiquetas se están mezclando, lee Runtimes de agentes antes de cambiar la configuración.

Elección rápida

Mapa de nombres

Los nombres son similares, pero no intercambiables:

Esto significa que una configuración puede contener intencionalmente referencias de modelo openai/* mientras los perfiles de autenticación apuntan a credenciales de clave de API o de OAuth de ChatGPT/Codex. Usa auth.order.openai para la configuración; openclaw doctor --fix reescribe referencias de modelos Codex heredadas, ids de perfiles de autenticación Codex heredados y orden de autenticación Codex heredado a la ruta canónica de OpenAI.

Vista previa limitada de GPT-5.6

OpenClaw reconoce los tres ids públicos de modelos GPT-5.6:

• openai/gpt-5.6-sol
• openai/gpt-5.6-terra
• openai/gpt-5.6-luna

Los tres exponen razonamiento max en el catálogo actual del servidor de aplicaciones de Codex. El anuncio de lanzamiento de OpenAI describe Sol como el nivel insignia, Terra como el nivel equilibrado y Luna como el nivel rápido y de menor costo. Consulta el anuncio de lanzamiento de GPT-5.6 y la guía de acceso a la vista previa.

El acceso está en lista de permitidos durante la vista previa y puede concederse por separado para la API y Codex. Un plan ChatGPT de pago por sí solo no concede acceso. OpenClaw mantiene openai/gpt-5.5 como valor predeterminado; seleccionar una referencia GPT-5.6 sin acceso devuelve el error de acceso de upstream en lugar de volver silenciosamente a otra opción.

Cobertura de funciones de OpenClaw

Embeddings de memoria

OpenClaw puede usar OpenAI, o un endpoint de embeddings compatible con OpenAI, para la indexación de memory_search y los embeddings de consulta:

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

Para endpoints compatibles con OpenAI que requieren etiquetas de embeddings asimétricas, establece queryInputType y documentInputType en memorySearch. OpenClaw reenvía esos valores como campos de solicitud input_type específicos del proveedor: los embeddings de consulta usan queryInputType; los fragmentos de memoria indexados y la indexación por lotes usan documentInputType. Consulta la referencia de configuración de memoria para ver el ejemplo completo.

Primeros pasos

Elige tu método de autenticación preferido y sigue los pasos de configuración.

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

{  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.5

openclaw models list --provider openai

{  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: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 }],      },    },  },}

Autenticación nativa de app-server de Codex

El arnés nativo de app-server de Codex usa refs de modelo openai/* más configuración de runtime omitida o proveedor/modelo agentRuntime.id: "codex", pero su autenticación sigue estando basada en cuenta. OpenClaw selecciona la autenticación en este orden:

1. Perfiles de autenticación de OpenAI ordenados para el agente, preferentemente bajo auth.order.openai. Ejecuta openclaw doctor --fix para migrar ids de perfil de autenticación heredados de Codex antiguos y el orden de autenticación heredado de Codex.
2. La cuenta existente del app-server, como un inicio de sesión local de ChatGPT en la CLI de Codex.
3. Solo para lanzamientos locales de app-server con stdio, CODEX_API_KEY, luego OPENAI_API_KEY, cuando el app-server informa que no hay cuenta y aún requiere autenticación de OpenAI.

Eso significa que un inicio de sesión local de suscripción de ChatGPT/Codex no se reemplaza solo porque el proceso del gateway también tenga OPENAI_API_KEY para modelos directos de OpenAI o embeddings. El respaldo de clave de API de entorno es solo la ruta local de stdio sin cuenta; no se envía a conexiones WebSocket de app-server. Cuando se selecciona un perfil de Codex de estilo suscripción, OpenClaw también mantiene CODEX_API_KEY y OPENAI_API_KEY fuera del proceso hijo de app-server stdio generado y envía las credenciales seleccionadas mediante el RPC de inicio de sesión del app-server. Cuando ese perfil de suscripción queda bloqueado por un límite de uso de Codex, OpenClaw puede rotar al siguiente perfil de clave de API openai:* ordenado sin cambiar el modelo seleccionado ni salir del arnés de Codex. Una vez que pasa la hora de reinicio de la suscripción, el perfil de suscripción vuelve a ser elegible.

Generación de imágenes

El Plugin openai incluido registra la generación de imágenes mediante la herramienta image_generate. Admite tanto generación de imágenes con clave de API de OpenAI como generación de imágenes con OAuth de Codex mediante la misma ref. de modelo openai/gpt-image-2.

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

gpt-image-2 es el valor predeterminado tanto para la generación de texto a imagen de OpenAI como para la edición de imágenes. gpt-image-1.5, gpt-image-1 y gpt-image-1-mini siguen siendo utilizables como sobrescrituras explícitas de modelo. Usa openai/gpt-image-1.5 para salida PNG/WebP con fondo transparente; la API actual de gpt-image-2 rechaza background: "transparent".

Para una solicitud con fondo transparente, los agentes deben llamar a image_generate con model: "openai/gpt-image-1.5", outputFormat: "png" o "webp", y background: "transparent"; la opción anterior de proveedor openai.background sigue siendo aceptada. OpenClaw también protege las rutas públicas de OpenAI y OAuth de OpenAI Codex reescribiendo las solicitudes transparentes predeterminadas de openai/gpt-image-2 a gpt-image-1.5; Azure y los endpoints personalizados compatibles con OpenAI conservan sus nombres configurados de despliegue/modelo.

La misma configuración se expone para ejecuciones de CLI sin interfaz:

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

Usa las mismas marcas --output-format y --background con openclaw infer image edit cuando comiences desde un archivo de entrada. --openai-background sigue estando disponible como alias específico de OpenAI. Usa --quality low|medium|high|auto cuando necesites controlar la calidad y el costo de OpenAI Images. Usa --openai-moderation low|auto para pasar la sugerencia de moderación específica del proveedor de OpenAI desde image generate o image edit.

Para instalaciones de ChatGPT/Codex OAuth, conserva la misma ref. openai/gpt-image-2. Cuando se configura un perfil OAuth de openai, OpenClaw resuelve ese token de acceso OAuth almacenado y envía las solicitudes de imagen a través del backend de Codex Responses. No intenta primero OPENAI_API_KEY ni hace fallback silencioso a una clave de API para esa solicitud. Configura models.providers.openai explícitamente con una clave de API, URL base personalizada o endpoint de Azure cuando quieras usar la ruta directa de la API de OpenAI Images en su lugar. Si ese endpoint de imagen personalizado está en una LAN o dirección privada de confianza, también establece browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true; OpenClaw mantiene bloqueados los endpoints de imagen privados/internos compatibles con OpenAI salvo que esta opción explícita esté presente.

Generar:

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

Generar un PNG transparente:

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

Editar:

/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

Generación de video

El Plugin openai incluido registra la generación de video mediante la herramienta video_generate.

Las solicitudes de imagen a video de OpenAI usan POST /v1/videos con una input_reference de imagen. Las ediciones de un solo video usan POST /v1/videos/edits con el video cargado en el campo video.

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

Contribución de prompt de GPT-5

OpenClaw agrega una contribución compartida de prompt de GPT-5 para ejecuciones de la familia GPT-5 en superficies de prompt ensambladas por OpenClaw. Se aplica por id de modelo, por lo que rutas de OpenClaw/proveedor como refs heredadas previas a reparación (ref heredada de Codex GPT-5.5), openrouter/openai/gpt-5.5, opencode/gpt-5.5 y otras refs compatibles con GPT-5 reciben la misma superposición. Los modelos GPT-4.x anteriores no.

El arnés nativo de Codex incluido no recibe esta superposición de GPT-5 de OpenClaw mediante instrucciones de desarrollador del app-server de Codex. Codex nativo conserva el comportamiento base, de modelo y de documentos de proyecto propiedad de Codex, mientras que OpenClaw deshabilita la personalidad integrada de Codex para hilos nativos, de modo que los archivos de personalidad del área de trabajo del agente sigan siendo autoritativos. OpenClaw contribuye solo contexto de runtime, como entrega de canal, herramientas dinámicas de OpenClaw, delegación ACP, contexto de área de trabajo y Skills de OpenClaw.

La contribución de GPT-5 agrega un contrato de comportamiento etiquetado para persistencia de persona, seguridad de ejecución, disciplina de herramientas, forma de salida, comprobaciones de finalización y verificación en prompts coincidentes ensamblados por OpenClaw. El comportamiento de respuesta específico del canal y de mensajes silenciosos permanece en el prompt de sistema compartido de OpenClaw y la política de entrega saliente. La capa de estilo de interacción amigable es independiente y configurable.

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

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

Voz y habla

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

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

Endpoints de Azure OpenAI

El proveedor openai incluido puede apuntar a un recurso de Azure OpenAI para la generación de imágenes mediante la sobrescritura de la URL base. En la ruta de generación de imágenes, OpenClaw detecta nombres de host de Azure en models.providers.openai.baseUrl y cambia automáticamente a la forma de solicitud de Azure.

Usa Azure OpenAI cuando:

• Ya tienes una suscripción, cuota o acuerdo empresarial de Azure OpenAI
• Necesitas residencia de datos regional o controles de cumplimiento que proporciona Azure
• Quieres mantener el tráfico dentro de una tenencia de Azure existente

Configuración

Para la generación de imágenes de Azure mediante el proveedor openai incluido, apunta models.providers.openai.baseUrl a tu recurso de Azure y establece apiKey en la clave de Azure OpenAI (no una clave de OpenAI Platform):

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

OpenClaw reconoce estos sufijos de host de Azure para la ruta de generación de imágenes de Azure:

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

Para solicitudes de generación de imágenes en un host de Azure reconocido, OpenClaw:

• Envía el encabezado api-key en lugar de Authorization: Bearer
• Usa rutas con alcance de despliegue (/openai/deployments/{deployment}/...)
• Añade ?api-version=... a cada solicitud
• Usa un tiempo de espera de solicitud predeterminado de 600 s para llamadas de generación de imágenes de Azure. Los valores timeoutMs por llamada siguen sobrescribiendo este predeterminado.

Otras URL base (OpenAI público, proxies compatibles con OpenAI) conservan la forma estándar de solicitud de imágenes de OpenAI.

Versión de API

Establece AZURE_OPENAI_API_VERSION para fijar una versión preview o GA específica de Azure para la ruta de generación de imágenes de Azure:

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

El valor predeterminado es 2024-12-01-preview cuando la variable no está definida.

Los nombres de modelo son nombres de despliegue

Azure OpenAI vincula modelos a despliegues. Para solicitudes de generación de imágenes de Azure enrutadas mediante el proveedor openai incluido, el campo model en OpenClaw debe ser el nombre de despliegue de Azure que configuraste en el portal de Azure, no el id. público del modelo de OpenAI.

Si creas un despliegue llamado gpt-image-2-prod que sirve gpt-image-2:

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

La misma regla de nombre de despliegue se aplica a las llamadas de generación de imágenes enrutadas mediante el proveedor openai incluido.

Disponibilidad regional

La generación de imágenes de Azure está disponible actualmente solo en un subconjunto de regiones (por ejemplo, eastus2, swedencentral, polandcentral, westus3, uaenorth). Consulta la lista actual de regiones de Microsoft antes de crear un despliegue y confirma que el modelo específico se ofrece en tu región.

Diferencias de parámetros

Azure OpenAI y OpenAI público no siempre aceptan los mismos parámetros de imagen. Azure puede rechazar opciones que OpenAI público permite (por ejemplo, ciertos valores de background en gpt-image-2) o exponerlas solo en versiones específicas del modelo. Estas diferencias provienen de Azure y del modelo subyacente, no de OpenClaw. Si una solicitud de Azure falla con un error de validación, revisa el conjunto de parámetros admitido por tu despliegue y versión de API específicos en el portal de Azure.

Configuración avanzada

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

Relacionado