Conecta OpenAI a OpenClaw: Guía de configuración rápida

¿Alguna vez te ha pasado que pierdes más tiempo configurando las API keys que escribiendo código? Gestionar diferentes modelos y métodos de autenticación puede ser un dolor de cabeza cuando solo quieres que las cosas funcionen.

Aquí tienes la guía para configurar OpenAI en OpenClaw sin complicaciones, para que puedas elegir el método que mejor se adapte a tu flujo de trabajo.

OpenAI

OpenAI ofrece APIs para desarrolladores para modelos GPT. Codex permite el inicio de sesión con ChatGPT para acceso por suscripción o mediante API key para acceso basado en uso. Codex cloud requiere iniciar sesión con ChatGPT. OpenAI soporta explícitamente el uso de OAuth por suscripción en herramientas externas como OpenClaw.

Opción A: OpenAI API key (OpenAI Platform)

Ideal para: acceso directo a la API y facturación basada en el uso. Consigue tu API key en el dashboard de OpenAI.

Configuración de la CLI

openclaw onboard --auth-choice openai-api-key
# or non-interactive
openclaw onboard --openai-api-key "$OPENAI_API_KEY"

Fragmento de configuración

{
  env: { OPENAI_API_KEY: "sk-..." },
  agents: { defaults: { model: { primary: "openai/gpt-5.4" } } },
}

La documentación actual de modelos de la API de OpenAI enumera gpt-5.4 y gpt-5.4-pro para el uso directo de la API de OpenAI. OpenClaw envía ambos a través de la ruta de Responses openai/*. OpenClaw oculta intencionadamente la fila obsoleta openai/gpt-5.3-codex-spark, porque las llamadas directas a la API de OpenAI la rechazan en el tráfico real.

OpenClaw no expone openai/gpt-5.3-codex-spark en la ruta directa de la API de OpenAI. pi-ai todavía incluye una fila integrada para ese modelo, pero las peticiones reales a la API de OpenAI lo rechazan actualmente. Spark se trata como un modelo exclusivo de Codex en OpenClaw.

Opción B: Suscripción de OpenAI Code (Codex)

Ideal para: usar el acceso por suscripción de ChatGPT/Codex en lugar de una API key. Codex cloud requiere iniciar sesión con ChatGPT, mientras que la CLI de Codex soporta inicio de sesión con ChatGPT o API key.

Configuración de la CLI (Codex OAuth)

# Run Codex OAuth in the wizard
openclaw onboard --auth-choice openai-codex

# Or run OAuth directly
openclaw models auth login --provider openai-codex

Fragmento de configuración (Suscripción Codex)

{
  agents: { defaults: { model: { primary: "openai-codex/gpt-5.4" } } },
}

La documentación actual de Codex de OpenAI lista gpt-5.4 como el modelo de Codex actual. OpenClaw mapea eso a openai-codex/gpt-5.4 para el uso de ChatGPT/Codex OAuth.

Si tu cuenta de Codex tiene acceso a Codex Spark, OpenClaw también soporta:

openai-codex/gpt-5.3-codex-spark

OpenClaw trata Codex Spark como exclusivo de Codex. No expone una ruta directa de API key para openai/gpt-5.3-codex-spark.

OpenClaw también mantiene openai-codex/gpt-5.3-codex-spark cuando pi-ai lo detecta. Considéralo como algo experimental y que depende de tus permisos de acceso: Codex Spark es independiente de GPT-5.4 /fast, y su disponibilidad depende de la cuenta de Codex / ChatGPT con la que hayas iniciado sesión.

Transporte por defecto

OpenClaw usa pi-ai para el streaming de modelos. Tanto para openai/* como para openai-codex/*, el transporte por defecto es "auto" (primero WebSocket, luego SSE como alternativa).

Puedes configurar agents.defaults.models.<provider/model>.params.transport:

"sse": fuerza SSE
"websocket": fuerza WebSocket
"auto": intenta WebSocket y luego cambia a SSE si falla

Para openai/* (Responses API), OpenClaw también activa el warm-up de WebSocket por defecto (openaiWsWarmup: true) cuando se usa el transporte WebSocket.

Documentación de OpenAI relacionada:

{
  agents: {
    defaults: {
      model: { primary: "openai-codex/gpt-5.4" },
      models: {
        "openai-codex/gpt-5.4": {
          params: {
            transport: "auto",
          },
        },
      },
    },
  },
}

Warm-up de WebSocket de OpenAI

Los documentos de OpenAI describen el warm-up como opcional. OpenClaw lo activa por defecto para openai/* para reducir la latencia del primer turno cuando se usa el transporte WebSocket.

Desactivar warm-up

{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.4": {
          params: {
            openaiWsWarmup: false,
          },
        },
      },
    },
  },
}

Activar warm-up explícitamente

{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.4": {
          params: {
            openaiWsWarmup: true,
          },
        },
      },
    },
  },
}

Procesamiento prioritario en OpenAI y Codex

La API de OpenAI expone el procesamiento prioritario mediante service_tier=priority. En OpenClaw, configura agents.defaults.models["<provider>/<model>"].params.serviceTier para pasar ese campo en los endpoints nativos de OpenAI/Codex Responses.

{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.4": {
          params: {
            serviceTier: "priority",
          },
        },
        "openai-codex/gpt-5.4": {
          params: {
            serviceTier: "priority",
          },
        },
      },
    },
  },
}

Los valores soportados son auto, default, flex y priority.

OpenClaw envía params.serviceTier tanto a las peticiones directas de openai/* Responses como a las peticiones de openai-codex/* Codex Responses cuando esos modelos apuntan a los endpoints nativos de OpenAI/Codex.

Comportamiento importante:

openai/* directo debe apuntar a api.openai.com
openai-codex/* debe apuntar a chatgpt.com/backend-api
Si diriges cualquier proveedor a través de otra URL base o proxy, OpenClaw no modificará service_tier

Modo rápido (fast mode) de OpenAI

OpenClaw expone un interruptor de modo rápido compartido para sesiones openai/* y openai-codex/*:

Chat/UI: /fast status|on|off
Configuración: agents.defaults.models["<provider>/<model>"].params.fastMode

Cuando el modo rápido está activado, OpenClaw lo mapea al procesamiento prioritario de OpenAI:

Las llamadas directas de openai/* Responses a api.openai.com envían service_tier = "priority"
Las llamadas de openai-codex/* Responses a chatgpt.com/backend-api también envían service_tier = "priority"
Se conservan los valores de service_tier existentes en el payload
El modo rápido no sobrescribe reasoning ni text.verbosity

Ejemplo:

{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.4": {
          params: {
            fastMode: true,
          },
        },
        "openai-codex/gpt-5.4": {
          params: {
            fastMode: true,
          },
        },
      },
    },
  },
}

Los ajustes manuales de la sesión tienen prioridad sobre la configuración. Si borras el ajuste manual en la UI de Sesiones, la sesión volverá al valor configurado por defecto.

Compactación en el lado del servidor de OpenAI Responses

Para modelos directos de OpenAI Responses (openai/* usando api: "openai-responses" con baseUrl en api.openai.com), OpenClaw ahora activa automáticamente las pistas de payload para la compactación en el lado del servidor de OpenAI:

Fuerza store: true (a menos que la compatibilidad del modelo establezca supportsStore: false)
Inyecta context_management: [{ type: "compaction", compact_threshold: ... }]

Por defecto, compact_threshold es el 70% del contextWindow del modelo (o 80000 cuando no está disponible).

Activar compactación en el lado del servidor explícitamente

Usa esto cuando quieras forzar la inyección de context_management en modelos de Responses compatibles (por ejemplo, Azure OpenAI Responses):

{
  agents: {
    defaults: {
      models: {
        "azure-openai-responses/gpt-5.4": {
          params: {
            responsesServerCompaction: true,
          },
        },
      },
    },
  },
}

Activar con un umbral personalizado

{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.4": {
          params: {
            responsesServerCompaction: true,
            responsesCompactThreshold: 120000,
          },
        },
      },
    },
  },
}

Desactivar compactación en el lado del servidor

{
  agents: {
    defaults: {
      models: {
        "openai/gpt-5.4": {
          params: {
            responsesServerCompaction: false,
          },
        },
      },
    },
  },
}

responsesServerCompaction solo controla la inyección de context_management. Los modelos directos de OpenAI Responses seguirán forzando store: true a menos que la compatibilidad indique supportsStore: false.

Notas

Las referencias de modelos siempre usan provider/model (consulta /concepts/models).
Los detalles de autenticación y las reglas de reutilización están en /concepts/oauth.

Siguientes pasos

AI Setup Assistant

OpenClaw Expert

Sigues atascado?

Si esta pagina no resolvio tu caso, pregunta a OpenClaw Expert para pasos concretos.