OpenAI

OpenAI proporciona APIs para desarrolladores para modelos GPT, y Codex también está disponible como agente de programación de planes 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 OpenAI. Los turnos de agentes integrados en modelos 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 disponible para superficies 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 la autenticación openai-codex para usar una suscripción ChatGPT/Codex, o configura un perfil de clave de API openai-codex cuando quieras usar intencionadamente autenticación con clave de API.
• APIs OpenAI que no son de agente - acceso directo a OpenAI Platform con facturación por 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 tanto referencias de modelo openai/* como perfiles de autenticación openai-codex. openclaw doctor --fix reescribe las referencias heredadas de modelo openai-codex/* a la ruta canónica de modelos OpenAI.

# Cobertura de funciones de OpenClaw

# Embeddings de memoria

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

{
  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 dentro de 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" },
      agentRuntime: { id: "codex" },
    },
  },
}

openclaw models status
openclaw models auth list --provider openai-codex
openclaw config get agents.defaults.model --json
openclaw config get agents.defaults.agentRuntime --json

openclaw models status --agent <id>
openclaw models auth list --agent <id> --provider openai-codex

openclaw doctor --fix
openclaw config validate

openclaw models auth login --provider openai-codex
openclaw models status --probe --probe-provider openai-codex

{
  models: {
    providers: {
      "openai-codex": {
        models: [{ id: "gpt-5.5", contextTokens: 160000 }],
      },
    },
  },
}

# Autenticación del app-server nativo de Codex

El entorno app-server nativo de Codex usa referencias de modelo openai/* más configuración de runtime omitida o agentRuntime.id: "codex", pero su autenticación sigue basándose en la cuenta. OpenClaw selecciona la autenticación en este orden:

1. Un perfil de autenticación openai-codex explícito de OpenClaw vinculado al agente.
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 por 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 fallback de clave de API de entorno es solo la ruta local por 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 app-server por stdio generado y envía las credenciales seleccionadas mediante el RPC de inicio de sesión del app-server.

# 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 con clave de API de OpenAI y generación de imágenes con OAuth de Codex mediante la misma referencia 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 de openai/gpt-image-2 a gpt-image-1.5; Azure y los endpoints personalizados compatibles con OpenAI conservan sus nombres de despliegue/modelo configurados.

La misma opción está expuesta 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 empezar desde un archivo de entrada. --openai-background sigue disponible como alias específico de OpenAI.

Para instalaciones con OAuth de Codex, conserva la misma referencia 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 Responses de Codex. No intenta 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 la ruta directa de la API Images 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 aceptació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 de prompt compartida de GPT-5 para ejecuciones de la familia GPT-5 entre proveedores. Se aplica por id de modelo, por lo que openai/gpt-5.5, referencias heredadas antes de la reparación como openai-codex/gpt-5.5, openrouter/openai/gpt-5.5, opencode/gpt-5.5 y otras referencias compatibles de GPT-5 reciben la misma superposición. Los modelos GPT-4.x antiguos no.

El entorno nativo incluido de Codex usa el mismo comportamiento de GPT-5 y la misma superposición de Heartbeat mediante instrucciones de desarrollador del app-server de Codex, por lo que las sesiones openai/gpt-5.x forzadas mediante agentRuntime.id: "codex" conservan la misma guía de seguimiento y Heartbeat proactivo aunque Codex sea responsable del resto del prompt del entorno.

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 respuesta específico del canal y de mensajes silenciosos permanece en el prompt de 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.

{
  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 anulando 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 regional de datos o controles de cumplimiento que Azure proporciona
• Quieres mantener el tráfico dentro de una tenencia de Azure existente

# Configuración

Para la generación de imágenes de Azure a través del 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 implementación (/openai/deployments/{deployment}/...)
• Anexa ?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 todavía anulan este valor predeterminado.

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

# Versión de API

Establece AZURE_OPENAI_API_VERSION para fijar una versión preliminar 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 implementación

Azure OpenAI vincula modelos a implementaciones. Para 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 implementación de Azure que configuraste en el portal de Azure, no el id de modelo público de OpenAI.

Si creas una implementación llamada 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 implementación 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 está disponible solo en un subconjunto de regiones (por ejemplo eastus2, swedencentral, polandcentral, westus3, uaenorth). Consulta la lista de regiones actual de Microsoft antes de crear una implementación 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 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, comprueba el conjunto de parámetros admitido por tu implementación y versión de API específicas en el portal de Azure.

# Configuración avanzada

{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.5": {
          params: { transport: "auto" },
        },
      },
    },
  },
}

// Disable warm-up
{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.5": {
          params: { openaiWsWarmup: false },
        },
      },
    },
  },
}

{
  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