OpenAI

OpenAI proporciona API para desarrolladores para modelos GPT, y Codex también está disponible como agente de programación de plan de ChatGPT a través de los clientes Codex de OpenAI. OpenClaw mantiene esas superficies separadas para que la configuración siga siendo predecible.

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

• 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 con clave de API de OpenAI compatible con Codex cuando quieras usar intencionadamente 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 modelo openai-codex/* 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 y flujos de trabajo externos como OpenClaw.

Proveedor, modelo, runtime y canal son capas separadas. Si esas etiquetas se están mezclando, lee runtimes de agente 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 intencionadamente referencias de modelo openai/* mientras los perfiles de autenticación siguen apuntando a credenciales compatibles con Codex. Prefiere auth.order.openai para configuraciones nuevas; los perfiles openai-codex:* existentes y auth.order.openai-codex siguen siendo compatibles. openclaw doctor --fix reescribe las referencias de modelo heredadas openai-codex/* a la ruta canónica de modelos de OpenAI.

Cobertura de características 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 embedding asimétricas, define queryInputType y documentInputType en memorySearch. OpenClaw los reenvía 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: "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 }],      },    },  },}

Autenticación nativa del servidor de aplicación de Codex

El arnés nativo del servidor de aplicación 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, preferiblemente en auth.order.openai. Los perfiles existentes openai-codex:* y auth.order.openai-codex siguen siendo válidos para instalaciones antiguas.
2. La cuenta existente del servidor de aplicación, como un inicio de sesión local de ChatGPT en Codex CLI.
3. Solo para lanzamientos locales del servidor de aplicación por stdio, CODEX_API_KEY y luego OPENAI_API_KEY, cuando el servidor de aplicación informa que no hay cuenta y todavía requiere autenticación de OpenAI.

Eso significa que un inicio de sesión local con 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 por env solo es la ruta local stdio sin cuenta; no se envía a conexiones WebSocket del servidor de aplicación. Cuando se selecciona un perfil de Codex de tipo suscripción, OpenClaw también mantiene CODEX_API_KEY y OPENAI_API_KEY fuera del proceso hijo stdio del servidor de aplicación generado y envía las credenciales seleccionadas mediante el RPC de inicio de sesión del servidor de aplicación. Cuando ese perfil de suscripción está 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 restablecimiento 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 generación de imágenes tanto con clave de API de OpenAI como 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 de proveedor antigua openai.background todavía se acepta. OpenClaw también protege las rutas públicas de OpenAI y OAuth de OpenAI Codex reescribiendo las solicitudes transparentes predeterminadas openai/gpt-image-2 a gpt-image-1.5; Azure y los endpoints personalizados compatibles con OpenAI conservan sus nombres de implementación/modelo configurados.

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 flags --output-format y --background con openclaw infer image edit al partir de un archivo de entrada. --openai-background sigue disponible como alias específico de OpenAI.

Para instalaciones con OAuth de Codex, conserva la misma ref. openai/gpt-image-2. Cuando se configura un perfil OAuth openai-codex, OpenClaw resuelve ese token de acceso OAuth almacenado y envía las solicitudes de imagen a través del backend de Responses de Codex. No prueba primero OPENAI_API_KEY ni recurre silenciosamente 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 imágenes de OpenAI en su lugar. Si ese endpoint de imagen personalizado está en una dirección LAN/privada de confianza, configura también browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true; OpenClaw mantiene bloqueados los endpoints de imagen privados/internos compatibles con OpenAI salvo que esta adhesió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.

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

Contribución de prompt de GPT-5

OpenClaw añade una contribución compartida de prompt de GPT-5 para ejecuciones de la familia GPT-5 en distintos proveedores. Se aplica por id de modelo, por lo que openai/gpt-5.5, referencias heredadas previas a la reparación como openai-codex/gpt-5.5, openrouter/openai/gpt-5.5, opencode/gpt-5.5 y otras referencias compatibles con GPT-5 reciben la misma superposición. Los modelos GPT-4.x anteriores no.

El arnés nativo de Codex incluido usa el mismo comportamiento de GPT-5 y la misma superposición de Heartbeat mediante las instrucciones de desarrollador del servidor de aplicaciones de Codex, por lo que las sesiones openai/gpt-5.x enrutadas a través de Codex conservan la misma guía de seguimiento y Heartbeat proactivo, aunque Codex controla el resto del prompt del arnés.

La contribución de GPT-5 añade un contrato de comportamiento etiquetado para la persistencia de la persona, la seguridad de ejecución, la disciplina de herramientas, la forma de salida, las comprobaciones de finalización y la verificación. El comportamiento de respuestas específico del canal y de mensajes silenciosos permanece en el prompt compartido del sistema de OpenClaw y en la política de entrega saliente. La guía de GPT-5 siempre está habilitada para los modelos coincidentes. La capa de estilo de interacción amistoso 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", voice: "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 sobrescribiendo 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 a la forma de solicitud de Azure automáticamente.

Usa Azure OpenAI cuando:

• Ya tengas una suscripción, cuota o acuerdo empresarial de Azure OpenAI
• Necesites residencia regional de datos o controles de cumplimiento que Azure proporciona
• Quieras 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 ámbito 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 valor predeterminado.

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

Versión de la API

Configura AZURE_OPENAI_API_VERSION para fijar una versión específica de Azure en vista previa o GA 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 los modelos a despliegues. Para las solicitudes de generación de imágenes de Azure enrutadas a través del 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 a través del proveedor openai incluido.

Disponibilidad regional

La generación de imágenes de Azure actualmente solo está disponible 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 ofrezca 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 de modelo específicas. Estas diferencias provienen de Azure y del modelo subyacente, no de OpenClaw. Si una solicitud de Azure falla con un error de validación, consulta 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: 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" },    },  },}

Relacionado