Visión general de la arquitectura de codex

源码版本rust-v0.145.0

codex es el coding agent (agente de código) de código abierto de OpenAI; esta versión es la reescritura en Rust (la versión temprana en TypeScript ha quedado relegada a codex-cli/ solo como envoltorio de instalación npm). El cuerpo principal del código está en codex-rs/, un Cargo workspace que cuelga 90+ crates independientes, cortados con granularidad fina por responsabilidad. Este sitio descompone capa por crate, y cada archivo clave lleva un SrcLink que enlaza directamente a la línea correspondiente en GitHub.

Estratificación global

Lista de los principales crates

Capa	crate	Responsabilidad
Entrada CLI	cli	dispatch de subcomandos, doctor, login, mcp_cmd
Núcleo del Agent	core	bucle principal del Agent, cliente LLM, compaction, hilo de sesión, herramientas
Protocolo de parche	apply-patch	formato de parche de texto apply_patch
Sandbox	sandboxing / linux-sandbox / bwrap / windows-sandbox-rs	aislamiento multiplataforma de comandos
Política de ejecución	execpolicy	clasificación de comandos y política de permisos
Ejecución	exec / exec-server	ejecución de comandos y protocolo exec-server
TUI	tui	UI de terminal, chatwidget, diff_model
App-server	app-server / app-server-protocol / app-server-transport	servicio de orquestación y protocolo
MCP	mcp-server / rmcp-client / codex-mcp / connectors	integración de Model Context Protocol
Provider	model-provider / model-provider-info / backend-client	abstracción de model provider
Cloud	cloud-tasks / cloud-config	ejecución de tareas en la nube
Configuración	config / codex-home	sistema de configuración y directorio home
Alrededores	prompts / skills / memories / hooks / plugin / rollout	prompts, skills, memorias, hooks, plugin, trace

Una frase por capa

• Entrada CLI: dispatch de subcomandos del comando codex; main.rs usa clap para parsear y luego enrutar a cada subcomando.
• Núcleo del Agent: el bucle principal del Agent consume Op, impulsa la llamada LLM y la ejecución de herramientas; CodexThread es la entrada de orquestación de la sesión.
• Ejecución en sandbox (sandbox): los comandos corren dentro del sandbox; execpolicy clasifica primero el comando para decidir permiso/bloqueo/aprobación, y luego lo pasa al sandbox de la plataforma para aislarlo.
• TUI/App-server: TUI es el frontend de terminal; App-server expone la capacidad del Agent mediante protocolo a IDEs/clientes externos.
• Provider/Cloud: model-provider abstrae distintos backends; cloud-tasks envía tareas a la nube para ejecutarlas.

Motivación de diseño

codex eligió reescribir en Rust; la motivación central es sandbox y rendimiento. Un coding agent tiene que ejecutar comandos shell arbitrarios en la máquina del usuario; sin aislamiento fiable de procesos no hay seguridad. El sistema de tipos y las abstracciones de coste cero de Rust hacen que la fragmentación fina de 90+ crates no introduzca overhead en tiempo de ejecución. El workspace corta por responsabilidad en crates, en lugar de un único crate grande, para favorecer compilación incremental y fronteras claras: tocar TUI no recompila core.

Lecturas equivocadas comunes

• «codex es una herramienta CLI» — solo aciertas por la mitad. La CLI es solo la entrada; lo que realmente corre es la combinación de tres capas: core + sandbox + tui/app-server.
• «La reescritura en Rust es por velocidad» — Rust aporta aislamiento de sandbox y seguridad a nivel de proceso; el rendimiento es un subproducto.
• «apply_patch es un formato privado de codex» — es un protocolo de parche de texto usado por codex: el modelo lo genera, y el crate apply-patch lo parsea y aplica.

Orden de lectura recomendado

1. Entrada CLI y dispatch de subcomandos — entra por el comando codex y mira cómo se dispatcha
2. Bucle principal del Agent — cómo el Agent consume Op para impulsar al LLM
3. Cliente LLM y Responses API — cómo hablar con el backend de OpenAI
4. Sandbox multiplataforma — cómo se aíslan los comandos
5. Clasificación de comandos en execpolicy — cómo se clasifican y permiten los comandos
6. Arquitectura de App-server — cómo se expone por protocolo al exterior

Tras leer esta línea, básicamente puedes explicar el camino completo de codex desde «el usuario escribe un comando» hasta «el LLM ejecuta herramientas y modifica archivos».