OpenAI

OpenClaw usa un único id de proveedor, openai, tanto para la autenticación directa con clave de API como para la autenticación mediante suscripción de ChatGPT/Codex. openai/* es la ruta de modelo canónica. Para los turnos del agente integrado cuya política de runtime no esté definida o sea auto, los datos de ruta de OpenAI determinan si OpenClaw puede seleccionar implícitamente el runtime incluido del servidor de aplicaciones de Codex. El prefijo openai/* por sí solo no selecciona ningún runtime.

• Modelos de agente - openai/* mediante el runtime seleccionado por la configuración explícita agentRuntime o por la política de ruta implícita de OpenAI. Inicie sesión con la autenticación de Codex para usar una suscripción de ChatGPT/Codex, o configure un perfil de autenticación con clave de API si desea facturación basada en claves.
• API de OpenAI ajenas al agente - acceso directo a OpenAI Platform, facturado por uso, mediante OPENAI_API_KEY o un perfil de autenticación con clave de API openai.
• Configuración heredada - las referencias codex/* y openai-codex/* se reparan como openai/* más agentRuntime.id: "codex" con ámbito de modelo mediante openclaw doctor --fix.

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

Seguimiento del uso y los costes

OpenClaw mantiene separados la cuota de suscripción y la facturación de la API de Platform:

• OAuth de ChatGPT/Codex muestra el plan de suscripción, los períodos de cuota y el saldo de créditos.
• OPENAI_ADMIN_KEY muestra 30 días de costes de la organización y uso de completions informados por el proveedor en Uso de Control UI, incluidos el gasto diario, los totales de solicitudes/tokens, los modelos principales y las categorías de costes.
• OPENAI_PROJECT_ID limita opcionalmente el historial de la Admin API a un proyecto.
• OpenClaw nunca envía OPENAI_API_KEY ni un perfil de inferencia openai a las API de la organización; esas credenciales pueden pertenecer a endpoints personalizados, de Azure o locales del agente.

Una clave de administración explícita tiene prioridad sobre OAuth. El historial informado por el proveedor no se combina con el coste estimado por OpenClaw a partir de las sesiones; puede incluir actividad de la API procedente de otros clientes y ajustes de facturación del proveedor.

La documentación del panel de uso de la API de OpenAI describe los requisitos de ser propietario de la organización y contar con permisos explícitos del Usage Dashboard para acceder a los datos de uso.

El proveedor, el modelo, el runtime y el canal son capas independientes. Si esas etiquetas se están confundiendo, consulte Runtimes de agente antes de cambiar la configuración.

Elección rápida

Mapa de nombres

Runtime implícito del agente

Cuando la política agentRuntime del proveedor/modelo no está definida o es auto, la política de ruta propiedad del proveedor de OpenAI elige el runtime implícito a partir del endpoint y el adaptador efectivos:

Una configuración agentRuntime.id explícita y no predeterminada del proveedor/modelo sigue siendo vinculante. Por ejemplo, agentRuntime.id: "openclaw" mantiene en OpenClaw una ruta que, de otro modo, sería apta para Codex, mientras que agentRuntime.id: "codex" exige Codex y falla de forma cerrada cuando la ruta efectiva no está declarada como compatible con Codex. La selección del runtime no cambia el tipo de credencial ni la facturación: la autenticación con clave de API de Platform y la autenticación mediante suscripción de ChatGPT/Codex siguen siendo distintas.

openclaw doctor --fix migra las referencias de modelo heredadas codex/* y openai-codex/*, los ids de perfil de autenticación de Codex heredados y las entradas de orden de autenticación de Codex heredadas a la ruta canónica openai. Las referencias de modelo migradas reciben agentRuntime.id: "codex" con ámbito de modelo; use auth.order.openai para las nuevas configuraciones de orden de autenticación.

Vista previa limitada de GPT-5.6

OpenClaw reconoce los ids de modelo exactos openai/gpt-5.6-sol, openai/gpt-5.6-terra y openai/gpt-5.6-luna. Los tres ofrecen los niveles de razonamiento xhigh y max en el catálogo actual. OpenAI describe Sol como el nivel insignia, Terra como el nivel equilibrado y Luna como el nivel rápido y de menor coste. Consulte el anuncio de lanzamiento de GPT-5.6 y la guía de acceso.

Con autenticación directa mediante clave de API de OpenAI, el id básico openai/gpt-5.6 es un alias de Sol y el valor predeterminado de la configuración nueva. El catálogo nativo de Codex no aplica ese alias de API directa en el cliente; según el acceso del espacio de trabajo, puede mostrar los ids exactos de Sol, Terra y Luna. Por tanto, la configuración nueva de OAuth de ChatGPT/Codex usa openai/gpt-5.6-sol. Compruebe la cuenta actual con:

openclaw models list --provider openai

El acceso de la organización de la API y el del espacio de trabajo de Codex pueden ser diferentes. Si GPT-5.6 no está disponible, seleccione GPT-5.5 explícitamente:

openclaw models set openai/gpt-5.5

OpenClaw muestra el error de acceso original y no sustituye silenciosamente una selección de GPT-5.6 por GPT-5.5.

Cobertura de funciones de OpenClaw

Embeddings de memoria

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

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

Para los endpoints compatibles con OpenAI que requieran etiquetas de embeddings asimétricas, establezca queryInputType y documentInputType en memory.search. OpenClaw los reenvía como campos de solicitud input_type específicos del proveedor: los embeddings de consultas utilizan queryInputType; los fragmentos de memoria indexados y la indexación por lotes utilizan documentInputType. Consulte la referencia de configuración de memoria para ver el ejemplo completo.

Primeros pasos

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

Autenticación del servidor de aplicaciones nativo de Codex

El entorno de servidor de aplicaciones nativo de Codex utiliza referencias de modelo openai/* cuando una ruta HTTPS oficial exacta y apta lo selecciona implícitamente, o cuando la configuración de proveedor/modelo agentRuntime.id: "codex" lo selecciona explícitamente. Su autenticación sigue estando basada en cuentas. OpenClaw selecciona la autenticación en este orden:

1. Perfiles de autenticación de OpenAI ordenados para el agente, preferiblemente en auth.order.openai. Ejecute openclaw doctor --fix para migrar identificadores anteriores de perfiles de autenticación heredados de Codex y el orden de autenticación.
2. La cuenta existente del servidor de aplicaciones, como un inicio de sesión local de ChatGPT en la CLI de Codex. Para el directorio principal aislado predeterminado del agente, OpenClaw enlaza esa cuenta nativa de la CLI con el servidor de aplicaciones mediante su RPC de inicio de sesión; no comparte la configuración, los plugins ni el almacén de hilos de la CLI.
3. Solo para ejecuciones locales del servidor de aplicaciones mediante stdio y únicamente cuando el servidor de aplicaciones no informa de ninguna cuenta: CODEX_API_KEY y después OPENAI_API_KEY.

Un inicio de sesión local de suscripción de ChatGPT/Codex no se sustituye solo porque el proceso del Gateway también disponga de OPENAI_API_KEY para modelos directos de OpenAI o representaciones vectoriales. La alternativa mediante clave de API del entorno solo se aplica a la ruta local de stdio sin cuenta; nunca se envía mediante conexiones WebSocket del servidor de aplicaciones. Cuando se selecciona un perfil de Codex basado en suscripción, OpenClaw también mantiene CODEX_API_KEY y OPENAI_API_KEY fuera del proceso hijo del servidor de aplicaciones stdio y envía las credenciales seleccionadas mediante el RPC de inicio de sesión del servidor de aplicaciones.

Cuando ese perfil de suscripción queda bloqueado por un límite de uso de Codex, OpenClaw marca el perfil como bloqueado hasta la hora de restablecimiento anunciada por Codex y permite que el orden de autenticación rote al siguiente perfil openai:*, sin cambiar el modelo seleccionado ni abandonar el entorno de Codex. Una vez transcurrida la hora de restablecimiento, el perfil de suscripción vuelve a ser apto.

Generación de imágenes

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

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

gpt-image-2 es el valor predeterminado para la generación de imágenes a partir de texto y la edición de imágenes de OpenAI. gpt-image-1.5, gpt-image-1 y gpt-image-1-mini siguen estando disponibles como sustituciones explícitas del modelo. Use openai/gpt-image-1.5 para obtener salidas PNG/WebP con fondo transparente; la API actual gpt-image-2 rechaza background: "transparent".

Para una solicitud con fondo transparente, invoque image_generate con model: "openai/gpt-image-1.5", outputFormat: "png" o "webp", y background: "transparent"; la opción anterior de proveedor 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 de openai/gpt-image-2 como gpt-image-1.5; Azure y los endpoints personalizados compatibles con OpenAI conservan sus nombres configurados de implementación/modelo.

La misma configuración está disponible para ejecuciones de la CLI sin interfaz gráfica:

openclaw infer image generate \  --model openai/gpt-image-1.5 \  --output-format png \  --background transparent \  --prompt "Una pegatina sencilla de un círculo rojo sobre un fondo transparente" \  --json

Use las mismas opciones --output-format y --background con openclaw infer image edit cuando parta de un archivo de entrada. --openai-background sigue estando disponible como alias específico de OpenAI. Use --quality low|medium|high|auto para controlar la calidad y el coste de las imágenes de OpenAI. Use --openai-moderation low|auto para pasar la indicación de moderación de OpenAI desde image generate o image edit.

Para las instalaciones OAuth de ChatGPT/Codex, mantenga la misma referencia openai/gpt-image-2. Cuando se configura un perfil OAuth openai, OpenClaw resuelve ese token de acceso OAuth almacenado y envía las solicitudes de imágenes mediante el backend Codex Responses; no intenta primero OPENAI_API_KEY ni recurre silenciosamente a una clave de API. Configure models.providers.openai explícitamente con una clave de API, una URL base personalizada o un endpoint de Azure cuando quiera usar en su lugar la ruta directa de la API de OpenAI Images. Si ese endpoint de imágenes personalizado se encuentra en una dirección LAN/privada de confianza, establezca también browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true; OpenClaw mantiene bloqueados los endpoints de imágenes privados/internos compatibles con OpenAI a menos que esta habilitación explícita esté presente.

Generar:

/tool image_generate model=openai/gpt-image-2 prompt="Un póster de lanzamiento refinado para OpenClaw en macOS" size=3840x2160 count=1

Generar un PNG transparente:

/tool image_generate model=openai/gpt-image-1.5 prompt="Una pegatina sencilla de un círculo rojo sobre un fondo transparente" outputFormat=png background=transparent

Editar:

/tool image_generate model=openai/gpt-image-2 prompt="Conserva la forma del objeto y cambia el material por vidrio translúcido" image=/path/to/reference.png size=1024x1536

Generación de vídeo

El plugin openai incluido registra la generación de vídeo mediante la herramienta video_generate.

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

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

Contribución al prompt de GPT-5

OpenClaw añade una contribución compartida al prompt de GPT-5 para los modelos de la familia GPT-5 en el proveedor openai (incluidas las referencias heredadas de Codex anteriores a la reparación que se normalizan a openai/*). Otros proveedores que también ofrecen identificadores de modelos de la familia GPT-5, como OpenRouter o las rutas de opencode, no reciben esta capa; se condiciona al identificador de proveedor openai, no solo al identificador de modelo. Los modelos GPT-4.x anteriores nunca la reciben.

El entorno nativo del servidor de aplicaciones de Codex no recibe el contrato de comportamiento de personalidad y disciplina de herramientas ni la capa de estilo de interacción cordial mediante instrucciones para desarrolladores; Codex nativo conserva el comportamiento base, de modelo y de documentación del proyecto propio de Codex, y OpenClaw desactiva la personalidad integrada de Codex para los hilos nativos, de modo que los archivos de personalidad del espacio de trabajo del agente sigan siendo la autoridad. OpenClaw solo aporta contexto de ejecución a los hilos nativos de Codex: entrega por canales, herramientas dinámicas de OpenClaw, delegación ACP, contexto del espacio de trabajo y Skills de OpenClaw. El texto de orientación de Heartbeat de esta misma contribución es la única excepción: los turnos de Heartbeat de Codex nativo sí lo reciben, insertado como instrucciones de colaboración específicas en lugar de mediante el enlace compartido de contribución al prompt.

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

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

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

Voz y habla

{  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 dirigirse a un recurso de Azure OpenAI para la generación de imágenes reemplazando la URL base. En la ruta de generación de imágenes, OpenClaw detecta los nombres de host de Azure en models.providers.openai.baseUrl y cambia automáticamente a la estructura de solicitud de Azure.

Use Azure OpenAI cuando:

• Ya disponga de una suscripción, cuota o acuerdo empresarial de Azure OpenAI
• Necesite la residencia regional de datos o los controles de cumplimiento que proporciona Azure
• Quiera mantener el tráfico dentro de una suscripción existente de Azure

Configuración

Para generar imágenes en Azure mediante el proveedor openai incluido, dirija models.providers.openai.baseUrl a su recurso de Azure y establezca 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 las 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
• Utiliza rutas limitadas a la implementación (/openai/deployments/{deployment}/...)
• Añade ?api-version=... a cada solicitud
• Utiliza un tiempo de espera predeterminado de 600s para las llamadas de generación de imágenes de Azure. Los valores de timeoutMs por llamada siguen reemplazando este valor predeterminado.

Las demás URL base (OpenAI público y proxies compatibles con OpenAI) conservan la estructura estándar de solicitud de imágenes de OpenAI.

Versión de la API

Establezca AZURE_OPENAI_API_VERSION para fijar una versión preliminar o con disponibilidad general 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á establecida.

Los nombres de modelo son nombres de implementación

Azure OpenAI vincula los modelos a implementaciones. Para las solicitudes de generación de imágenes de Azure enrutadas mediante el proveedor openai incluido, el campo model de OpenClaw debe ser el nombre de la implementación de Azure configurado en el portal de Azure, no el identificador público del modelo de OpenAI.

Si crea una implementación llamada gpt-image-2-prod que sirve gpt-image-2:

/tool image_generate model=openai/gpt-image-2-prod prompt="Un cartel sencillo" size=1024x1024 count=1

La misma regla del nombre de implementación se aplica a cualquier llamada de generación de imágenes enrutada mediante el proveedor openai incluido.

Disponibilidad regional

Actualmente, la generación de imágenes de Azure solo está disponible en un subconjunto de regiones (por ejemplo, eastus2, swedencentral, polandcentral, westus3, uaenorth). Consulte la lista actual de regiones de Microsoft antes de crear una implementación y confirme que el modelo específico esté disponible en su región.

Diferencias entre parámetros

Azure OpenAI y OpenAI público no siempre aceptan los mismos parámetros de imagen. Azure puede rechazar opciones permitidas por OpenAI público (por ejemplo, determinados valores de background en gpt-image-2) o exponerlas únicamente en versiones específicas del modelo. Estas diferencias proceden de Azure y del modelo subyacente, no de OpenClaw. Si una solicitud de Azure falla con un error de validación, consulte en el portal de Azure el conjunto de parámetros compatible con su implementación y versión de API específicas.

Configuración avanzada

Los siguientes ejemplos de params por modelo determinan la solicitud del proveedor integrado de OpenClaw. Configurarlos constituye un comportamiento de solicitud definido, por lo que una ruta auto que cumpla los requisitos permanece en OpenClaw en lugar de seleccionar Codex implícitamente. El entorno del servidor de aplicaciones nativo de Codex administra su propio transporte y sus propios ajustes de solicitud; un agentRuntime.id: "codex" explícito produce un fallo seguro cuando la ruta efectiva no está declarada como compatible con 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" },    },  },}

Temas relacionados