OpenAI

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

• Modelos de agente - openai/* mediante el entorno de ejecución seleccionado por la configuración explícita de agentRuntime o 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 mediante clave de API si desea facturación basada en claves.
• API de OpenAI ajenas a agentes - acceso directo a OpenAI Platform, facturado por uso, mediante OPENAI_API_KEY o un perfil openai de autenticación mediante clave de API.
• Configuración heredada - openclaw doctor --fix repara las referencias antiguas a modelos Codex y los ids de perfil para convertirlos a openai/*.

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

Seguimiento del uso y los costes

OpenClaw mantiene separadas 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 en Usage de la interfaz de control 30 días de costes de la organización y uso de completions notificados por el proveedor, 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 API de administración 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 notificado por el proveedor no se combina con el coste estimado que OpenClaw deriva 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 propietario de la organización y de permiso explícito para el panel de uso necesarios para acceder a los datos de uso.

El proveedor, el modelo, el entorno de ejecución y el canal son capas independientes. Si se están mezclando esas etiquetas, consulte Entornos de ejecución de agentes antes de cambiar la configuración.

Elección rápida

Mapa de nombres

Entorno de ejecución implícito del agente

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

Un agentRuntime.id explícito no predeterminado de proveedor/modelo sigue siendo la autoridad. 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 aplica un cierre seguro cuando la ruta efectiva no está declarada como compatible con Codex. La selección del entorno de ejecución no cambia el tipo de credencial ni la facturación: la autenticación mediante clave de API de Platform y la autenticación de suscripción de ChatGPT/Codex siguen siendo distintas.

openclaw doctor --fix migra las referencias heredadas a modelos Codex, los ids heredados de perfiles de autenticación de Codex y las entradas heredadas del orden de autenticación a la ruta canónica openai. Use auth.order.openai para la nueva configuración del 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 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 una 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, una configuración nueva de OAuth de ChatGPT/Codex usa openai/gpt-5.6-sol. Consulte 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 usar OpenAI, o un endpoint de embeddings compatible con OpenAI, para la indexación y los embeddings de consultas de memory_search:

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

Para los endpoints compatibles con OpenAI que requieran etiquetas de embeddings asimétricas, configure queryInputType y documentInputType en memorySearch. OpenClaw los reenvía como campos de solicitud input_type específicos del proveedor: los embeddings de consultas usan queryInputType; los fragmentos de memoria indexados y la indexación por lotes usan 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.5", contextTokens: 160000 }],      },    },  },}

Autenticación del servidor de aplicaciones nativo de Codex

El arnés del servidor de aplicaciones nativo de Codex usa referencias de modelos openai/* cuando una ruta HTTPS oficial exacta y apta lo selecciona implícitamente, o cuando agentRuntime.id: "codex" del proveedor/modelo 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 los 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 conecta 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 inicios locales del servidor de aplicaciones mediante stdio, y únicamente cuando el servidor de aplicaciones informa que no hay ninguna cuenta: CODEX_API_KEY y después OPENAI_API_KEY.

Un inicio de sesión local de suscripción a ChatGPT/Codex no se sustituye únicamente porque el proceso del Gateway también tenga OPENAI_API_KEY para modelos directos de OpenAI o embeddings. La alternativa mediante clave de API del entorno solo se aplica a la ruta local mediante stdio sin cuenta; nunca se envía mediante conexiones WebSocket al servidor de aplicaciones. Cuando se selecciona un perfil de Codex de tipo suscripción, OpenClaw también evita que CODEX_API_KEY y OPENAI_API_KEY lleguen al proceso secundario del servidor de aplicaciones mediante stdio y, en su lugar, envía las credenciales seleccionadas mediante el RPC de inicio de sesión del servidor de aplicaciones.

Cuando ese perfil de suscripción está 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 arnés de Codex. Una vez que pasa 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 tanto la generación de imágenes 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 siendo utilizables como sobrescrituras explícitas del modelo. Use openai/gpt-image-1.5 para generar PNG/WebP con fondo transparente; la API actual de gpt-image-2 rechaza background: "transparent".

Para una solicitud con fondo transparente, llame a image_generate con model: "openai/gpt-image-1.5", outputFormat: "png" o "webp" y background: "transparent"; la opción anterior del proveedor openai.background aún 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 sin interfaz de la CLI:

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 los mismos indicadores --output-format y --background con openclaw infer image edit cuando parta de un archivo de entrada. --openai-background sigue disponible como alias específico de OpenAI. Use --quality low|medium|high|auto para controlar la calidad y el coste de OpenAI Images. Use --openai-moderation low|auto para pasar la indicación de moderación de OpenAI desde image generate o image edit.

Para instalaciones con OAuth de ChatGPT/Codex, mantenga la misma referencia 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 imágenes mediante el backend de respuestas de Codex; no prueba 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 desee usar la ruta directa de la API de imágenes de OpenAI. Si ese endpoint personalizado de imágenes se encuentra en una dirección privada/LAN de confianza, también establezca browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true; OpenClaw mantiene bloqueados los endpoints privados/internos de imágenes compatibles con OpenAI salvo que esta activació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 a 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 imagen input_reference. 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 arnés nativo del servidor de aplicaciones de Codex no recibe mediante las instrucciones del desarrollador el contrato de comportamiento de personalidad y disciplina de herramientas, ni la capa de estilo de interacción cordial; Codex nativo conserva el comportamiento base, del modelo y de los documentos del proyecto que pertenece a 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 mantengan 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, inyectado como instrucciones específicas de colaboración en lugar de mediante el mecanismo 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 específico de los canales para las respuestas y los mensajes silenciosos permanece en el prompt compartido del sistema 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

{  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 usar 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 al formato de solicitud de Azure.

Use Azure OpenAI cuando:

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

Configuración

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

Las demás URL base (OpenAI público y proxies compatibles con OpenAI) mantienen el formato 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 de 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 modelos 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 implementación de Azure configurado en el portal de Azure, no el identificador público del modelo de OpenAI.

Si crea una implementación denominada gpt-image-2-prod que proporciona gpt-image-2:

/tool image_generate model=openai/gpt-image-2-prod prompt="Un póster limpio" size=1024x1024 count=1

La misma regla de 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 que OpenAI público permite (por ejemplo, determinados valores de background en gpt-image-2) o exponerlas solo 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 admitido por su implementación y versión de la API específicas.

Configuración avanzada

Los siguientes ejemplos de params por modelo determinan la solicitud del proveedor integrada de OpenClaw. Su configuración constituye un comportamiento de solicitud definido explícitamente, por lo que una ruta auto que, de otro modo, sería apta permanece en OpenClaw en lugar de seleccionar Codex de forma implícita. El entorno nativo del servidor de aplicaciones de Codex gestiona su propio transporte y configuración de solicitudes; un agentRuntime.id: "codex" explícito falla de forma segura 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" },    },  },}

Contenido relacionado