Codex SDK

Si usas Codex mediante Codex CLI, la extensión de IDE o Codex cloud, también puedes controlarlo mediante programación.

Usa el SDK cuando necesites:

• Controlar Codex como parte de tu canalización de CI/CD
• Crear tu propio agente que pueda interactuar con Codex para realizar tareas de ingeniería complejas
• Incorporar Codex en tus propias herramientas y flujos de trabajo internos
• Integrar Codex en tu propia aplicación

Usa Codex SDK para los hilos de Codex centrados en programación. Si Codex es uno de los especialistas dentro de un flujo de trabajo orquestado más amplio, ejecuta Codex CLI como servidor MCP y orquéstalo con Agents SDK.

Si tienes acceso a la versión beta y necesitas análisis de repositorios o cambios con hallazgos de seguridad estructurados y cobertura, usa Codex Security TypeScript SDK.

Biblioteca de TypeScript

La biblioteca de TypeScript permite que tu aplicación inicie, continúe y reanude hilos locales de Codex.

Usa la biblioteca en el lado del servidor; requiere Node.js 18 o una versión posterior.

Instalación

Para comenzar, instala Codex SDK mediante npm:

npm install @openai/codex-sdk

Uso

Inicia un hilo con Codex y ejecútalo con tu indicación.

const codex = new Codex();
const thread = codex.startThread();
const result = await thread.run(
  "Make a plan to diagnose and fix the CI failures"
);

console.log(result.finalResponse);

Vuelve a llamar a run() para continuar en el mismo hilo, o reanuda un hilo anterior proporcionando su ID.

// running the same thread
const result = await thread.run("Implement the plan");

console.log(result.finalResponse);

// resuming past thread

const threadId = "<thread-id>";
const thread2 = codex.resumeThread(threadId);
const result2 = await thread2.run("Pick up where you left off");

console.log(result2.finalResponse);

Para obtener más información, consulta el repositorio de TypeScript.

Biblioteca de Python

Python SDK controla el app-server local de Codex mediante JSON-RPC. Requiere Python 3.10 o una versión posterior. Las compilaciones publicadas del SDK incluyen una dependencia fijada del entorno de ejecución de Codex CLI.

Instalación

Para instalar el SDK, ejecuta:

pip install openai-codex

Las compilaciones publicadas del SDK usan automáticamente su entorno de ejecución fijado. Pasa CodexConfig(codex_bin=...) solo cuando quieras ejecutar intencionadamente un ejecutable local específico de Codex.

Mientras Python SDK esté en versión beta, pip install openai-codex selecciona la compilación beta publicada más reciente. Cuando exista una versión estable del SDK, usa pip install --pre openai-codex para optar por compilaciones preliminares más recientes.

Uso

Inicia Codex, crea un hilo y ejecuta una indicación:

from openai_codex import Codex, Sandbox

with Codex() as codex:
    thread = codex.thread_start(
        model="gpt-5.6-terra",
        sandbox=Sandbox.workspace_write,
    )
    result = thread.run("Make a plan to diagnose and fix the CI failures")
    print(result.final_response)

Usa AsyncCodex cuando tu aplicación ya sea asíncrona:

import asyncio

from openai_codex import AsyncCodex


async def main() -> None:
    async with AsyncCodex() as codex:
        thread = await codex.thread_start(model="gpt-5.6-terra")
        result = await thread.run("Implement the plan")
        print(result.final_response)


asyncio.run(main())

Configuraciones predefinidas del sandbox

Usa las mismas configuraciones predefinidas de Sandbox al crear un hilo o cambiar su acceso al sistema de archivos para un turno posterior:

from openai_codex import Codex, Sandbox

with Codex() as codex:
    thread = codex.thread_start(sandbox=Sandbox.workspace_write)
    thread.run("Make the requested change.")
    review = thread.run("Review the diff only.", sandbox=Sandbox.read_only)

Configuraciones predefinidas disponibles:

• Sandbox.read_only: Lee archivos sin permitir escrituras.
• Sandbox.workspace_write: Lee archivos y escribe dentro del espacio de trabajo y de las raíces configuradas con permisos de escritura.
• Sandbox.full_access: Ejecuta sin restricciones de acceso al sistema de archivos.

Cuando omites sandbox=, app-server usa su configuración predeterminada. Un sandbox pasado a run(...) o turn(...) se aplica a ese turno y a los turnos posteriores del hilo.

Para obtener más información, consulta el repositorio de Python.