Saltar al contenido principal

​
OpenAI

OpenAI proporciona API para desarrolladores para modelos GPT. OpenClaw admite dos rutas de autenticación:
  • Clave de API — acceso directo a OpenAI Platform con facturación según el uso (modelos openai/*)
  • Suscripción de Codex — inicio de sesión de ChatGPT/Codex con acceso por suscripción (modelos openai-codex/*)
OpenAI admite explícitamente el uso de OAuth de suscripción en herramientas y flujos de trabajo externos como OpenClaw.

​
Primeros pasos

Elige tu método de autenticación preferido y sigue los pasos de configuración.
Ideal para: acceso directo a la API y facturación según el uso.
1

Obtén tu clave de API

Crea o copia una clave de API desde el panel de OpenAI Platform.
2

Ejecuta la incorporación

openclaw onboard --auth-choice openai-api-key
O pasa la clave directamente:
openclaw onboard --openai-api-key "$OPENAI_API_KEY"
3

Verifica que el modelo esté disponible

openclaw models list --provider openai

​
Resumen de rutas

Model refRutaAuth
openai/gpt-5.4API directa de OpenAI PlatformOPENAI_API_KEY
openai/gpt-5.4-proAPI directa de OpenAI PlatformOPENAI_API_KEY
El inicio de sesión de ChatGPT/Codex se enruta mediante openai-codex/*, no openai/*.

​
Ejemplo de configuración

{
  env: { OPENAI_API_KEY: "sk-..." },
  agents: { defaults: { model: { primary: "openai/gpt-5.4" } } },
}
OpenClaw no expone openai/gpt-5.3-codex-spark en la ruta directa de API. Las solicitudes en vivo a la API de OpenAI rechazan ese modelo. Spark es solo de Codex.

​
Generación de imágenes

El Plugin openai incluido registra la generación de imágenes mediante la herramienta image_generate.
CapabilityValue
Modelo predeterminadoopenai/gpt-image-1
Máximo de imágenes por solicitud4
Modo de ediciónHabilitado (hasta 5 imágenes de referencia)
Sustituciones de tamañoCompatibles
Relación de aspecto / resoluciónNo se reenvían a la API de OpenAI Images
{
  agents: {
    defaults: {
      imageGenerationModel: { primary: "openai/gpt-image-1" },
    },
  },
}
Consulta Generación de imágenes para ver los parámetros compartidos de la herramienta, la selección de proveedor y el comportamiento de conmutación por error.

​
Generación de video

El Plugin openai incluido registra la generación de video mediante la herramienta video_generate.
CapabilityValue
Modelo predeterminadoopenai/sora-2
ModosTexto a video, imagen a video, edición de un solo video
Entradas de referencia1 imagen o 1 video
Sustituciones de tamañoCompatibles
Otras sustitucionesaspectRatio, resolution, audio, watermark se ignoran con una advertencia de la herramienta
{
  agents: {
    defaults: {
      videoGenerationModel: { primary: "openai/sora-2" },
    },
  },
}
Consulta Generación de video para ver los parámetros compartidos de la herramienta, la selección de proveedor y el comportamiento de conmutación por error.

​
Contribución de prompt de GPT-5

OpenClaw agrega una contribución de prompt de GPT-5 específica de OpenAI para ejecuciones de la familia GPT-5 de openai/* y openai-codex/*. Vive en el Plugin de OpenAI incluido, se aplica a IDs de modelo como gpt-5, gpt-5.2, gpt-5.4 y gpt-5.4-mini, y no se aplica a modelos GPT-4.x más antiguos. 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. El comportamiento específico del canal para respuestas y mensajes silenciosos permanece en el prompt del sistema compartido 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 amigable es independiente y configurable.
ValueEffect
"friendly" (predeterminado)Habilita la capa de estilo de interacción amigable
"on"Alias de "friendly"
"off"Desactiva solo la capa de estilo amigable
{
  plugins: {
    entries: {
      openai: { config: { personality: "friendly" } },
    },
  },
}
Los valores no distinguen entre mayúsculas y minúsculas en tiempo de ejecución, por lo que "Off" y "off" desactivan la capa de estilo amigable.

​
Voz y habla

El Plugin openai incluido registra la síntesis de voz para la superficie messages.tts.
SettingConfig pathDefault
Modelomessages.tts.providers.openai.modelgpt-4o-mini-tts
Vozmessages.tts.providers.openai.voicecoral
Velocidadmessages.tts.providers.openai.speed(sin configurar)
Instruccionesmessages.tts.providers.openai.instructions(sin configurar, solo gpt-4o-mini-tts)
Formatomessages.tts.providers.openai.responseFormatopus para notas de voz, mp3 para archivos
Clave de APImessages.tts.providers.openai.apiKeyUsa OPENAI_API_KEY como alternativa
URL basemessages.tts.providers.openai.baseUrlhttps://api.openai.com/v1
Modelos disponibles: gpt-4o-mini-tts, tts-1, tts-1-hd. Voces disponibles: alloy, ash, ballad, cedar, coral, echo, fable, juniper, marin, onyx, nova, sage, shimmer, verse.
{
  messages: {
    tts: {
      providers: {
        openai: { model: "gpt-4o-mini-tts", voice: "coral" },
      },
    },
  },
}
Configura OPENAI_TTS_BASE_URL para sustituir la URL base de TTS sin afectar el endpoint de la API de chat.
El Plugin openai incluido registra la transcripción en tiempo real para el Plugin Voice Call.
SettingConfig pathDefault
Modeloplugins.entries.voice-call.config.streaming.providers.openai.modelgpt-4o-transcribe
Duración del silencio...openai.silenceDurationMs800
Umbral de VAD...openai.vadThreshold0.5
Clave de API...openai.apiKeyUsa OPENAI_API_KEY como alternativa
Usa una conexión WebSocket a wss://api.openai.com/v1/realtime con audio G.711 u-law.
El Plugin openai incluido registra voz en tiempo real para el Plugin Voice Call.
SettingConfig pathDefault
Modeloplugins.entries.voice-call.config.realtime.providers.openai.modelgpt-realtime
Voz...openai.voicealloy
Temperature...openai.temperature0.8
Umbral de VAD...openai.vadThreshold0.5
Duración del silencio...openai.silenceDurationMs500
Clave de API...openai.apiKeyUsa OPENAI_API_KEY como alternativa
Admite Azure OpenAI mediante las claves de configuración azureEndpoint y azureDeployment. Admite llamadas bidireccionales a herramientas. Usa formato de audio G.711 u-law.

​
Configuración avanzada

OpenClaw usa WebSocket primero con alternativa SSE ("auto") tanto para openai/* como para openai-codex/*.En modo "auto", OpenClaw:
  • Reintenta un fallo temprano de WebSocket antes de volver a SSE
  • Tras un fallo, marca WebSocket como degradado durante ~60 segundos y usa SSE durante el período de enfriamiento
  • Adjunta encabezados estables de identidad de sesión y turno para reintentos y reconexiones
  • Normaliza los contadores de uso (input_tokens / prompt_tokens) entre variantes de transporte
ValueBehavior
"auto" (predeterminado)WebSocket primero, alternativa SSE
"sse"Forzar solo SSE
"websocket"Forzar solo WebSocket
{
  agents: {
    defaults: {
      models: {
        "openai-codex/gpt-5.4": {
          params: { transport: "auto" },
        },
      },
    },
  },
}
Documentación relacionada de OpenAI:
OpenClaw habilita el calentamiento de WebSocket de forma predeterminada para openai/* para reducir la latencia del primer turno.
// Desactivar el calentamiento
{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.4": {
          params: { openaiWsWarmup: false },
        },
      },
    },
  },
}
OpenClaw expone un interruptor compartido de modo rápido tanto para openai/* como para openai-codex/*:
  • Chat/UI: /fast status|on|off
  • Configuración: agents.defaults.models["<provider>/<model>"].params.fastMode
Cuando está habilitado, OpenClaw asigna el modo rápido al procesamiento prioritario de OpenAI (service_tier = "priority"). Los valores existentes de service_tier se conservan, y el modo rápido no reescribe reasoning ni text.verbosity.
{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.4": { params: { fastMode: true } },
        "openai-codex/gpt-5.4": { params: { fastMode: true } },
      },
    },
  },
}
Las sustituciones a nivel de sesión prevalecen sobre la configuración. Borrar la sustitución de sesión en la UI de sesiones devuelve la sesión al valor predeterminado configurado.
La API de OpenAI expone el procesamiento prioritario mediante service_tier. Configúralo por modelo en OpenClaw:
{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.4": { params: { serviceTier: "priority" } },
        "openai-codex/gpt-5.4": { params: { serviceTier: "priority" } },
      },
    },
  },
}
Valores compatibles: auto, default, flex, priority.
serviceTier solo se reenvía a endpoints nativos de OpenAI (api.openai.com) y endpoints nativos de Codex (chatgpt.com/backend-api). Si enrutas cualquiera de los proveedores mediante un proxy, OpenClaw deja service_tier sin cambios.
Para modelos directos de OpenAI Responses (openai/* en api.openai.com), OpenClaw habilita automáticamente Compaction del lado del servidor:
  • Fuerza store: true (a menos que la compatibilidad del modelo establezca supportsStore: false)
  • Inyecta context_management: [{ type: "compaction", compact_threshold: ... }]
  • compact_threshold predeterminado: 70% de contextWindow (o 80000 cuando no está disponible)
Útil para endpoints compatibles como Azure OpenAI Responses:
{
  agents: {
    defaults: {
      models: {
        "azure-openai-responses/gpt-5.4": {
          params: { responsesServerCompaction: true },
        },
      },
    },
  },
}
responsesServerCompaction solo controla la inyección de context_management. Los modelos directos de OpenAI Responses siguen forzando store: true a menos que la compatibilidad establezca supportsStore: false.
Para ejecuciones de la familia GPT-5 en openai/* y openai-codex/*, OpenClaw puede usar un contrato de ejecución embebido más estricto:
{
  agents: {
    defaults: {
      embeddedPi: { executionContract: "strict-agentic" },
    },
  },
}
Con strict-agentic, OpenClaw:
  • Ya no trata un turno de solo plan como progreso satisfactorio cuando hay disponible una acción de herramienta
  • Reintenta el turno con una guía de actuar ahora
  • Habilita automáticamente update_plan para trabajo sustancial
  • Muestra un estado explícito de bloqueo si el modelo sigue planificando sin actuar
Se limita solo a ejecuciones de la familia GPT-5 de OpenAI y Codex. Otros proveedores y familias de modelos más antiguas mantienen el comportamiento predeterminado.
OpenClaw trata los endpoints directos de OpenAI, Codex y Azure OpenAI de forma distinta a los proxies /v1 genéricos compatibles con OpenAI:Rutas nativas (openai/*, openai-codex/*, Azure OpenAI):
  • Conservan reasoning: { effort: "none" } solo para modelos que admiten el esfuerzo none de OpenAI
  • Omiten el razonamiento desactivado para modelos o proxies que rechazan reasoning.effort: "none"
  • Usan por defecto esquemas de herramientas en modo estricto
  • Adjuntan encabezados de atribución ocultos solo en hosts nativos verificados
  • Conservan la modelación de solicitudes exclusiva de OpenAI (service_tier, store, compatibilidad de razonamiento, pistas de caché de prompt)
Rutas proxy/compatibles:
  • Usan un comportamiento de compatibilidad más flexible
  • No fuerzan esquemas de herramientas estrictos ni encabezados exclusivos nativos
Azure OpenAI usa transporte nativo y comportamiento de compatibilidad, pero no recibe los encabezados de atribución ocultos.

​
Relacionado

Selección de modelos

Elegir proveedores, referencias de modelos y comportamiento de conmutación por error.

Generación de imágenes

Parámetros compartidos de herramientas de imágenes y selección de proveedor.

Generación de video

Parámetros compartidos de herramientas de video y selección de proveedor.

OAuth y autenticación

Detalles de autenticación y reglas de reutilización de credenciales.