Servidor de aplicaciones | Crear con Codex

Codex app-server es la interfaz que Codex utiliza para proporcionar funcionalidades a clientes avanzados (por ejemplo, la extensión de Codex para VS Code). Úsela cuando quiera integrar Codex profundamente en su propio producto: autenticación, historial de conversaciones, aprobaciones y eventos transmitidos del agente. La implementación de app-server es de código abierto y está disponible en el repositorio de Codex en GitHub (openai/codex/codex-rs/app-server). Consulte la página Código abierto para ver la lista completa de componentes de código abierto de Codex.

Conectar la interfaz de terminal de la CLI

El modo de interfaz de terminal remota permite ejecutar app-server en una máquina y conectar la interfaz de terminal de la CLI de Codex desde otra. Inicie un agente de escucha WebSocket:

codex app-server --listen ws://127.0.0.1:4500

A continuación, conecte la interfaz de terminal:

codex --remote ws://127.0.0.1:4500

Para una conexión no local, configure la autenticación de WebSocket y proteja la conexión con TLS. Guarde el token de portador en una variable de entorno y pase su nombre en lugar de introducir el token en la línea de comandos:

export CODEX_REMOTE_TOKEN="$(cat "$HOME/.codex/app-server-token")"
codex --remote wss://remote-host:4500 \
  --remote-auth-token-env CODEX_REMOTE_TOKEN

La opción --remote acepta endpoints ws://, wss://, unix:// y unix://PATH. Use WebSockets sin cifrar únicamente para localhost o para una conexión con reenvío de puertos SSH.

Conectar un host remoto de Code Mode

De forma predeterminada, app-server inicia un host local de Code Mode. Para usar en su lugar un host remoto, pase su URL segura de WebSocket:

codex app-server --code-mode-host wss://code-mode.example.com/host

--code-mode-host controla la conexión saliente de app-server a su host de Code Mode. No cambia --listen, que controla cómo se conectan los clientes a app-server. Todos los hilos del mismo proceso de app-server comparten la conexión seleccionada con el host de Code Mode.

Use wss:// para un host remoto. Use ws:// únicamente para una conexión local o con reenvío SSH. El comando de app-server y el transporte WebSocket son experimentales y no son compatibles con cargas de trabajo de producción.

Protocolo

Al igual que MCP, codex app-server admite comunicación bidireccional mediante mensajes JSON-RPC 2.0 (con el encabezado "jsonrpc":"2.0" omitido durante la transmisión).

Transportes compatibles:

stdio (--listen stdio://, predeterminado): JSON delimitado por saltos de línea (JSONL).
websocket (--listen ws://IP:PORT, experimental y no compatible): un mensaje JSON-RPC por cada trama de texto WebSocket.
Socket Unix (--listen unix:// o --listen unix://PATH): conexiones WebSocket mediante el socket de control predeterminado de app-server de Codex o una ruta de socket Unix personalizada, usando el protocolo de enlace HTTP Upgrade estándar.
off (--listen off): no expone ningún transporte local.

Cuando se ejecuta con --listen ws://IP:PORT, el mismo agente de escucha también proporciona sondas HTTP básicas de estado:

GET /readyz devuelve 200 OK cuando el agente de escucha acepta conexiones nuevas.
GET /healthz devuelve 200 OK cuando la solicitud no incluye un encabezado Origin.
Las solicitudes con un encabezado Origin se rechazan con 403 Forbidden.

El transporte WebSocket es experimental y no es compatible. Los agentes de escucha locales como ws://127.0.0.1:PORT son adecuados para flujos de trabajo de localhost y de reenvío de puertos SSH. Durante el despliegue, los agentes de escucha WebSocket que no son de bucle invertido permiten actualmente conexiones no autenticadas de forma predeterminada; por ello, configure la autenticación de WebSocket antes de exponer uno de forma remota.

Indicadores de autenticación de WebSocket compatibles:

--ws-auth capability-token --ws-token-file /absolute/path
--ws-auth capability-token --ws-token-sha256 HEX
--ws-auth signed-bearer-token --ws-shared-secret-file /absolute/path

Para tokens de portador firmados, también puede establecer --ws-issuer, --ws-audience y --ws-max-clock-skew-seconds. Los clientes presentan la credencial como Authorization: Bearer <token> durante el protocolo de enlace WebSocket, y app-server aplica la autenticación antes de initialize de JSON-RPC.

Prefiera --ws-token-file a pasar tokens de portador sin procesar en la línea de comandos. Use --ws-token-sha256 únicamente cuando el cliente mantenga el token original de alta entropía en un almacén de secretos local independiente; el hash solo sirve como verificador y los clientes siguen necesitando el token original.

En modo WebSocket, app-server usa colas con capacidad limitada. Cuando la cola de solicitudes entrantes está llena, el servidor rechaza las solicitudes nuevas con el código de error JSON-RPC -32001 y el mensaje "Server overloaded; retry later." Los clientes deben volver a intentarlo con un retraso de crecimiento exponencial y una variación aleatoria.

Esquema de mensajes

Las solicitudes incluyen method, params y id:

{ "method": "thread/start", "id": 10, "params": { "model": "gpt-5.6-terra" } }

Las respuestas repiten el id con result o error:

{ "id": 10, "result": { "thread": { "id": "thr_123" } } }

{ "id": 10, "error": { "code": 123, "message": "Something went wrong" } }

Las notificaciones omiten id y usan únicamente method y params:

{ "method": "turn/started", "params": { "turn": { "id": "turn_456" } } }

Puede generar un esquema de TypeScript o un paquete de JSON Schema desde la CLI. Cada salida es específica de la versión de Codex que ejecutó, por lo que los artefactos generados coinciden exactamente con esa versión:

codex app-server generate-ts --out ./schemas
codex app-server generate-json-schema --out ./schemas

Primeros pasos

Inicie el servidor con codex app-server (transporte stdio predeterminado), codex app-server --listen ws://127.0.0.1:4500 (WebSocket TCP) o codex app-server --listen unix:// (socket Unix predeterminado).
Conecte un cliente mediante el transporte seleccionado y envíe initialize seguido de la notificación initialized.
Inicie un hilo y un turno; después, siga leyendo las notificaciones del flujo de transporte activo.

Ejemplo (Node.js / TypeScript):




const proc = spawn("codex", ["app-server"], {
  stdio: ["pipe", "pipe", "inherit"],
});
const rl = readline.createInterface({ input: proc.stdout });

const send = (message: unknown) => {
  proc.stdin.write(`${JSON.stringify(message)}\n`);
};

let threadId: string | null = null;

rl.on("line", (line) => {
  const msg = JSON.parse(line) as any;
  console.log("server:", msg);

  if (msg.id === 1 && msg.result?.thread?.id && !threadId) {
    threadId = msg.result.thread.id;
    send({
      method: "turn/start",
      id: 2,
      params: {
        threadId,
        input: [{ type: "text", text: "Summarize this repo." }],
      },
    });
  }
});

send({
  method: "initialize",
  id: 0,
  params: {
    clientInfo: {
      name: "my_product",
      title: "My Product",
      version: "0.1.0",
    },
  },
});
send({ method: "initialized", params: {} });
send({ method: "thread/start", id: 1, params: { model: "gpt-5.6-terra" } });

Elementos fundamentales

Hilo: una conversación entre un usuario y el agente de Codex. Los hilos contienen turnos.
Turno: una única solicitud del usuario y el trabajo posterior del agente. Los turnos contienen elementos y transmiten actualizaciones incrementales.
Elemento: una unidad de entrada o salida (mensaje del usuario, mensaje del agente, ejecución de comandos, cambio de archivos, llamada a una herramienta y más).

Use las API de hilos para crear, enumerar o archivar conversaciones. Gestione una conversación con las API de turnos y transmita el progreso mediante notificaciones de turnos.

Resumen del ciclo de vida

Inicializar una vez por conexión: inmediatamente después de abrir una conexión de transporte, envíe una solicitud initialize con los metadatos de su cliente y, a continuación, emita initialized. El servidor rechaza cualquier solicitud de esa conexión anterior a este protocolo de enlace.
Iniciar (o reanudar) un hilo: llame a thread/start para una conversación nueva, a thread/resume para continuar una existente o a thread/fork para bifurcar el historial en un nuevo id de hilo.
Comenzar un turno: llame a turn/start con el threadId de destino y la entrada del usuario. Los campos opcionales reemplazan el modelo, la personalidad, cwd, la política de entorno aislado y otros valores.
Orientar un turno activo: llame a turn/steer para añadir la entrada del usuario al turno actualmente en curso sin crear un turno nuevo.
Transmitir eventos: después de turn/start, siga leyendo las notificaciones en stdout: thread/archived, thread/unarchived, item/started, item/completed, item/agentMessage/delta, el progreso de las herramientas y otras actualizaciones.
Finalizar el turno: el servidor emite turn/completed con el estado final cuando el modelo termina o después de una cancelación turn/interrupt.

Inicialización

Los clientes deben enviar una única solicitud initialize por conexión de transporte antes de invocar cualquier otro método en esa conexión y, a continuación, confirmarla con una notificación initialized. Las solicitudes enviadas antes de la inicialización reciben un error Not initialized, y las llamadas initialize repetidas en la misma conexión devuelven Already initialized.

El servidor devuelve la cadena del agente de usuario que presentará a los servicios upstream, junto con los valores platformFamily y platformOs que describen el destino de ejecución. Establezca clientInfo para identificar su integración.

initialize.params.capabilities también admite estas capacidades del cliente:

optOutNotificationMethods: nombres exactos de métodos de notificación que se suprimirán para esta conexión. La coincidencia es exacta (sin comodines ni prefijos); los nombres desconocidos se aceptan y se ignoran.
requestAttestation: habilita la solicitud attestation/generate iniciada por el servidor. Los hosts de escritorio que proporcionan certificación upstream responden con un valor { "token": "..." } opaco.
mcpServerOpenaiFormElicitation: permite que los servidores MCP downstream envíen la variante de formato extendido de OpenAI de mcpServer/elicitation/request.

Importante: Use clientInfo.name para identificar su cliente ante OpenAI Compliance Logs Platform. Si está desarrollando una nueva integración de Codex destinada al uso empresarial, póngase en contacto con OpenAI para que se añada a una lista de clientes conocidos. Para obtener más contexto, consulte la referencia de registros de Codex.

Ejemplo (de la extensión de Codex para VS Code):

{
  "method": "initialize",
  "id": 0,
  "params": {
    "clientInfo": {
      "name": "codex_vscode",
      "title": "Codex VS Code Extension",
      "version": "0.1.0"
    }
  }
}

Ejemplo con exclusión de notificaciones:

{
  "method": "initialize",
  "id": 1,
  "params": {
    "clientInfo": {
      "name": "my_client",
      "title": "My Client",
      "version": "0.1.0"
    },
    "capabilities": {
      "experimentalApi": true,
      "optOutNotificationMethods": ["thread/started", "item/agentMessage/delta"]
    }
  }
}

Adhesión a la API experimental

Algunos métodos y campos de app-server están restringidos intencionadamente mediante la capacidad experimentalApi.

Omita capabilities (o establezca experimentalApi en false) para permanecer en la superficie estable de la API; el servidor rechazará los métodos y campos experimentales.
Establezca capabilities.experimentalApi en true para habilitar los métodos y campos experimentales.

{
  "method": "initialize",
  "id": 1,
  "params": {
    "clientInfo": {
      "name": "my_client",
      "title": "My Client",
      "version": "0.1.0"
    },
    "capabilities": {
      "experimentalApi": true
    }
  }
}

Si un cliente envía un método o campo experimental sin adherirse, app-server lo rechaza con:

<descriptor> requires experimentalApi capability

Resumen de la API

thread/start: crea un hilo nuevo; emite thread/started y le suscribe automáticamente a los eventos de turnos y elementos de ese hilo.
thread/resume: vuelve a abrir un hilo existente por su id para que las llamadas posteriores a turn/start le añadan contenido.
thread/fork: bifurca un hilo en un nuevo id de hilo copiando el historial almacenado. Pase lastTurnId para copiar el historial hasta ese turno y omitir los turnos posteriores, o ephemeral: true para crear una bifurcación en memoria. Emite thread/started para el hilo nuevo; los hilos devueltos incluyen forkedFromId cuando está disponible.
thread/read: lee un hilo almacenado por su id sin reanudarlo; establezca includeTurns para devolver el historial completo de turnos. Los objetos thread devueltos incluyen el valor de ejecución status.
thread/list: pagina los registros de hilos almacenados; admite paginación basada en cursores, además de modelProviders, sourceKinds, archived, isPinned, cwd, useStateDbOnly, searchTerm y los filtros experimentales parentThreadId o ancestorThreadId. Los objetos thread devueltos incluyen el valor de ejecución status.
thread/turns/list: experimental; pagina el historial de turnos de un hilo almacenado sin reanudarlo. itemsView controla si los elementos de los turnos se omiten, se resumen o se cargan por completo.
thread/items/list: experimental; pagina los elementos persistentes de un hilo, con la opción de restringirlos a un turnId. El almacén de hilos activo debe admitir la paginación de elementos.
thread/loaded/list: enumera los id de los hilos cargados actualmente en memoria.
thread/name/set: establece o actualiza el nombre visible para el usuario de un hilo cargado o de un rollout persistente; emite thread/name/updated.
thread/goal/set: establece el objetivo de un hilo; emite thread/goal/updated.
thread/goal/get: lee el objetivo actual de un hilo.
thread/goal/clear: borra el objetivo de un hilo; emite thread/goal/cleared.
thread/metadata/update: modifica los metadatos almacenados de un hilo respaldado por SQLite, incluidos gitInfo y isPinned persistentes.
thread/archive: mueve el archivo de registro de un hilo al directorio archivado e intenta archivar los registros de los hilos descendientes generados que aún no estén archivados; devuelve {} cuando se realiza correctamente y emite thread/archived por cada hilo archivado.
thread/delete: elimina permanentemente un hilo activo o archivado persistente y todos sus hilos descendientes generados; devuelve {} cuando se realiza correctamente y emite thread/deleted por cada hilo eliminado.
thread/unsubscribe: cancela la suscripción de esta conexión a los eventos de turnos y elementos del hilo. Si era el último suscriptor, el servidor descarga el hilo tras un periodo de gracia de inactividad sin suscriptores y emite thread/closed.
thread/unarchive: restaura el rollout de un hilo archivado en el directorio de sesiones activas; devuelve el thread restaurado y emite thread/unarchived.
thread/status/changed: notificación emitida cuando cambia el valor de ejecución status de un hilo cargado.
thread/compact/start: activa la compactación del historial de conversación de un hilo; devuelve {} inmediatamente mientras el progreso se transmite mediante las notificaciones turn/* y item/*.
thread/shellCommand: ejecuta un comando del shell iniciado por el usuario en un hilo. Se ejecuta fuera del entorno aislado, con acceso completo, y no hereda la política de entorno aislado del hilo.
thread/backgroundTerminals/clean: detiene todas las terminales en segundo plano en ejecución de un hilo (experimental; requiere capabilities.experimentalApi).
thread/backgroundTerminals/list: enumera las terminales en segundo plano en ejecución de un hilo cargado (experimental; requiere capabilities.experimentalApi).
thread/backgroundTerminals/terminate: finaliza una terminal en segundo plano en ejecución mediante el processId de app-server (experimental; requiere capabilities.experimentalApi).
thread/rollback: obsoleto; elimina los últimos N turnos del contexto en memoria y conserva un marcador de reversión; devuelve el thread actualizado.
turn/start: añade la entrada del usuario a un hilo e inicia la generación de Codex; responde con el turn inicial y transmite eventos. Para collaborationMode, settings.developer_instructions: null significa «usar las instrucciones integradas para el modo seleccionado».
thread/inject_items: añade elementos sin procesar de Responses API al historial visible para el modelo de un hilo cargado sin iniciar un turno del usuario.
turn/steer: añade la entrada del usuario al turno activo en curso de un hilo; devuelve el turnId aceptado.
turn/interrupt: solicita la cancelación de un turno en curso; si se realiza correctamente, devuelve {} y el turno termina con status: "interrupted".
review/start: inicia el revisor de Codex para un hilo; emite los elementos enteredReviewMode y exitedReviewMode.
command/exec: ejecuta un único comando en el entorno aislado del servidor sin iniciar un hilo ni un turno.
command/exec/write: escribe bytes stdin en una sesión command/exec en ejecución o cierra stdin.
command/exec/resize: cambia el tamaño de una sesión command/exec en ejecución respaldada por PTY.
command/exec/terminate: detiene una sesión command/exec en ejecución.
command/exec/outputDelta (notificación): se emite para fragmentos de stdout/stderr codificados en base64 procedentes de una sesión command/exec de transmisión.
process/spawn: inicia una sesión de proceso explícita fuera del entorno aislado de Codex (experimental; requiere capabilities.experimentalApi).
process/writeStdin: escribe bytes de stdin en una sesión process/spawn en ejecución o cierra stdin (experimental).
process/resizePty: cambia el tamaño de una sesión de proceso en ejecución respaldada por PTY (experimental).
process/kill: finaliza una sesión de proceso en ejecución (experimental).
process/outputDelta y process/exited (notificación): se emiten para la salida transmitida del proceso y su estado de salida (experimental).
model/list: enumera los modelos disponibles (establezca includeHidden: true para incluir entradas con hidden: true) con opciones de esfuerzo, un upgrade opcional y inputModalities.
modelProvider/capabilities/read: lee los límites de capacidad del proveedor para combinaciones de modelo y proveedor.
experimentalFeature/list: enumera indicadores de funciones con metadatos de la etapa del ciclo de vida y paginación mediante cursor.
experimentalFeature/enablement/set: modifica la configuración de ejecución en memoria de claves de funciones compatibles, como apps y plugins.
environment/info: experimental; se conecta a un entorno de ejecución configurado y devuelve su shell y el directorio de trabajo predeterminado.
permissionProfile/list: enumera los perfiles de permisos beta e indica si los requisitos efectivos los permiten, con paginación mediante cursor.
collaborationMode/list: enumera los ajustes predefinidos del modo de colaboración (experimental, sin paginación).
skills/list: enumera las skills de uno o varios valores cwd (admite forceReload y el valor opcional perCwdExtraUserRoots).
skills/extraRoots/set: reemplaza las raíces adicionales del proceso usadas para detectar skills independientes sin conservarlas.
skills/changed (notificación): se emite cuando cambian los archivos locales de skills supervisados.
hooks/list: enumera los enlaces del ciclo de vida detectados para uno o varios valores cwd.
marketplace/add: añade un marketplace remoto de plugins y lo conserva en la configuración de marketplaces del usuario.
marketplace/remove: elimina un marketplace configurado y su raíz de marketplace instalada cuando existe.
marketplace/upgrade: actualiza un marketplace Git configurado o todos los marketplaces Git configurados cuando se omite el nombre del marketplace.
plugin/list: en desarrollo; enumera los marketplaces de plugins detectados y el estado de los plugins, incluidos los metadatos de las políticas de instalación y autenticación, los errores de carga del marketplace, los id de plugins destacados y los metadatos de fuentes de plugins locales, Git, del registro de paquetes o remotas. Los resúmenes pueden incluir version remoto, localVersion local, iconos claros/oscuros estructurados y installPolicySource, que puede ser null, WORKSPACE_SETTING o IMPLICIT_CANONICAL_APP para las filas remotas actuales. No llame aún a este método desde clientes de producción.
plugin/read: en desarrollo; lee un plugin por la ruta del marketplace o por el nombre del marketplace remoto y el nombre del plugin, incluidas las skills, las aplicaciones, los nombres de servidores MCP y un shareUrl de plugin remoto cuando el catálogo remoto lo proporciona. No llame aún a este método desde clientes de producción.
plugin/install: en desarrollo; instala un plugin desde la ruta de un marketplace o el nombre de un marketplace remoto. No llame aún a este método desde clientes de producción.
plugin/uninstall: en desarrollo; desinstala un plugin instalado. No llame aún a este método desde clientes de producción.
plugin/skill/read: lee bajo demanda el Markdown de una skill de plugin remoto mediante el marketplace remoto, el id del plugin y el nombre de la skill.
app/installed: lee el estado de ejecución de las aplicaciones instaladas, incluidos los estados efectivos de habilitación y disponibilidad para llamadas de cada aplicación.
app/list: enumera las aplicaciones (conectores) disponibles con paginación y metadatos de accesibilidad y habilitación.
app/read: obtiene metadatos y resúmenes opcionales de herramientas solo para visualización correspondientes a determinados id de aplicaciones.
skills/config/write: habilita o deshabilita skills por ruta.
mcpServer/oauth/login: inicia un acceso mediante OAuth para un servidor MCP configurado; devuelve una URL de autorización y emite mcpServer/oauthLogin/completed al finalizar.
tool/requestUserInput: presenta al usuario entre una y tres preguntas breves para una llamada a una herramienta (experimental); las preguntas pueden establecer isOther para una opción de formato libre.
mcpServer/elicitation/request (solicitud del servidor): solicita al cliente datos de un formulario estructurado o la confirmación de un flujo de URL solicitado por un servidor MCP.
item/permissions/requestApproval (solicitud del servidor): solicita al cliente que conceda un subconjunto de los permisos de red o del sistema de archivos requeridos por la herramienta integrada request_permissions.
config/mcpServer/reload: vuelve a cargar la configuración del servidor MCP desde el disco y pone en cola una actualización para los hilos cargados.
mcpServerStatus/list: enumera los servidores MCP, las herramientas, los recursos y el estado de autenticación (paginación con cursor y límite). Use detail: "full" para obtener todos los datos o detail: "toolsAndAuthOnly" para omitir los recursos.
mcpServer/resource/read: lee un único recurso MCP mediante un servidor MCP inicializado.
mcpServer/tool/call: llama a una herramienta del servidor MCP configurado de un hilo.
mcpServer/startupStatus/updated (notificación): se emite cuando cambia el estado de inicio del servidor MCP configurado de un hilo cargado.
windowsSandbox/setupStart: inicia la configuración del entorno aislado de Windows para el modo elevated o unelevated; devuelve una respuesta rápidamente y emite windowsSandbox/setupCompleted más adelante.
feedback/upload: envía un informe de comentarios (clasificación, motivo o registros opcionales e id de conversación, además de archivos adjuntos extraLogFiles opcionales).
config/read: obtiene la configuración efectiva del disco después de resolver las capas de configuración.
externalAgentConfig/detect: detecta artefactos de agentes externos que se pueden migrar mediante includeHome y el valor opcional cwds; cada elemento detectado incluye cwd (null para el directorio principal).
externalAgentConfig/import: aplica los elementos seleccionados de migración de agentes externos pasando valores migrationItems explícitos con cwd (null para el directorio principal). Los tipos de elementos compatibles incluyen configuración, skills, AGENTS.md, plugins, configuración de servidores MCP, subagentes, enlaces, comandos y sesiones; las importaciones no vacías emiten externalAgentConfig/import/progress y externalAgentConfig/import/completed a medida que termina el trabajo. Las importaciones de plugins y sesiones pueden completarse de forma asíncrona.
config/value/write: escribe una única clave o valor de configuración en el archivo config.toml del usuario en el disco.
config/batchWrite: aplica modificaciones de configuración de forma atómica al archivo config.toml del usuario en el disco.
configRequirements/read: obtiene requisitos de requirements.toml o MDM, incluida la configuración administrada exacta, las listas de permitidos, los valores featureRequirements fijados y los requisitos de residencia y red (o null si no ha configurado ninguno).
fs/readFile, fs/writeFile, fs/createDirectory, fs/getMetadata, fs/readDirectory, fs/remove, fs/copy, fs/watch, fs/unwatch y fs/changed (notificación): operan sobre rutas absolutas del sistema de archivos mediante la API v2 del sistema de archivos de app-server.

Los resúmenes de plugins incluyen una unión source. Los plugins locales devuelven { "type": "local", "path": ... }, las entradas de marketplaces respaldadas por Git devuelven { "type": "git", "url": ..., "path": ..., "refName": ..., "sha": ... }, las entradas del registro de paquetes devuelven { "type": "npm", "package": ..., "version": ..., "registry": ... } y las entradas del catálogo remoto devuelven { "type": "remote" }. Para las entradas que solo existen en el catálogo remoto, PluginMarketplaceEntry.path puede ser null; pase remoteMarketplaceName en lugar de marketplacePath al leer o instalar esos plugins.

Modelos

Enumerar modelos (`model/list`)

Llame a model/list para detectar los modelos disponibles y sus capacidades antes de mostrar selectores de modelos o personalidades.

{ "method": "model/list", "id": 6, "params": { "limit": 20, "includeHidden": false } }
{ "id": 6, "result": {
  "data": [{
    "id": "gpt-5.6-sol",
    "model": "gpt-5.6-sol",
    "displayName": "GPT-5.6-Sol",
    "hidden": false,
    "defaultReasoningEffort": "low",
    "supportedReasoningEfforts": [{
      "reasoningEffort": "low",
      "description": "Fast responses with lighter reasoning"
    }],
    "inputModalities": ["text", "image"],
    "supportsPersonality": true,
    "isDefault": true
  }],
  "nextCursor": null
} }

Cada entrada de modelo puede incluir:

supportedReasoningEfforts: opciones de esfuerzo compatibles con el modelo.
defaultReasoningEffort: esfuerzo predeterminado sugerido para los clientes.
upgrade: id opcional del modelo recomendado para actualizar, destinado a las solicitudes de migración de los clientes.
upgradeInfo: metadatos opcionales de actualización para las solicitudes de migración de los clientes.
hidden: indica si el modelo está oculto en la lista predeterminada del selector.
inputModalities: tipos de entrada compatibles con el modelo (por ejemplo, text, image).
supportsPersonality: indica si el modelo admite instrucciones específicas de la personalidad, como /personality.
isDefault: indica si el modelo es el predeterminado recomendado.

De forma predeterminada, model/list devuelve únicamente los modelos visibles en el selector. Establezca includeHidden: true si necesita la lista completa y quiere filtrarla en el cliente mediante hidden.

Cuando falta inputModalities (catálogos de modelos antiguos), trátelo como ["text", "image"] para mantener la compatibilidad con versiones anteriores.

Enumerar funciones experimentales (`experimentalFeature/list`)

Use este endpoint para detectar indicadores de funciones con metadatos y la etapa del ciclo de vida:

{ "method": "experimentalFeature/list", "id": 7, "params": { "limit": 20 } }
{ "id": 7, "result": {
  "data": [{
    "name": "unified_exec",
    "stage": "beta",
    "displayName": "Unified exec",
    "description": "Use the unified PTY-backed execution tool.",
    "announcement": "Beta rollout for improved command execution reliability.",
    "enabled": false,
    "defaultEnabled": false
  }],
  "nextCursor": null
} }

stage puede ser beta, underDevelopment, stable, deprecated o removed. Para indicadores que no sean beta, displayName, description y announcement pueden ser null.

Inspeccionar un entorno de ejecución (experimental)

Use environment/info para inspeccionar un entorno remoto configurado antes de comenzar a trabajar en él. El método requiere capabilities.experimentalApi = true.

{ "method": "environment/info", "id": 8, "params": { "environmentId": "devbox" } }
{ "id": 8, "result": {
  "shell": { "name": "zsh", "path": "/bin/zsh" },
  "cwd": "file:///workspace/project"
} }

cwd puede ser null. Cuando está presente, es un URI file: canónico que usa la sintaxis de rutas nativa del entorno. Los id de entorno desconocidos y los fallos de conexión o protocolo devuelven errores de solicitud.

Hilos

thread/read lee un hilo almacenado sin suscribirse a él; establezca includeTurns para incluir los turnos.
thread/turns/list es experimental y pagina el historial de turnos de un hilo almacenado sin reanudarlo. Use itemsView para elegir si los elementos de los turnos se omiten, se resumen o se cargan por completo.
thread/items/list es experimental y pagina los elementos persistentes del hilo, con la opción de restringirlos a un turno.
thread/list admite paginación mediante cursor, además de los filtros modelProviders, sourceKinds, archived, isPinned, cwd, useStateDbOnly, searchTerm y los experimentales parentThreadId o ancestorThreadId.
thread/loaded/list devuelve los id de los hilos que están actualmente en memoria.
thread/archive mueve el registro JSONL persistente del hilo al directorio archivado e intenta archivar los registros de los hilos descendientes generados que aún no estén archivados.
thread/delete elimina permanentemente un hilo activo o archivado persistente y sus hilos descendientes generados.
thread/metadata/update modifica los metadatos almacenados del hilo, incluidos gitInfo y isPinned persistentes.
thread/unsubscribe cancela la suscripción de la conexión actual a un hilo cargado y puede activar thread/closed después de un periodo de gracia de inactividad.
thread/unarchive restaura el rollout de un hilo archivado en el directorio de sesiones activas.
thread/compact/start activa la compactación y devuelve {} inmediatamente.
thread/rollback está obsoleto. Elimina los últimos N turnos del contexto en memoria y registra un marcador de reversión en el registro JSONL persistente del hilo.
thread/inject_items añade elementos sin procesar de Responses API al historial visible para el modelo de un hilo cargado sin iniciar un turno del usuario.

Iniciar o reanudar un hilo

Inicie un hilo nuevo cuando necesite una nueva conversación de Codex.

{ "method": "thread/start", "id": 10, "params": {
  "model": "gpt-5.6-terra",
  "cwd": "/Users/me/project",
  "approvalPolicy": "never",
  "sandbox": "workspaceWrite",
  "personality": "friendly",
  "serviceName": "my_app_server_client"
} }
{ "id": 10, "result": {
  "thread": {
    "id": "thr_123",
    "sessionId": "thr_123",
    "preview": "",
    "ephemeral": false,
    "modelProvider": "openai",
    "createdAt": 1730910000
  }
} }
{ "method": "thread/started", "params": { "thread": { "id": "thr_123" } } }

serviceName es opcional. Establézcalo cuando quiera que app-server etiquete las métricas del hilo con el nombre de servicio de su integración.

thread/start, thread/resume y thread/fork devuelven instructionSources, una matriz de rutas de archivos de instrucciones cargados. Cada ruta usa la sintaxis absoluta nativa de su entorno de origen, incluso en el caso de entornos remotos.

Los clientes experimentales pueden establecer historyMode en thread/start como "legacy" (valor predeterminado) o "paginated". La creación paginada de hilos aún no es compatible y devuelve el error JSON-RPC -32601. App-server puede enumerar y leer resúmenes de registros paginados existentes, pero las lecturas del historial completo, la paginación de turnos y la reanudación se bloquean de forma segura hasta que se admita el historial paginado.

Los clientes beta que se adhieran a capabilities.experimentalApi pueden pasar el id de un perfil de permisos con nombre en permissions en lugar del campo heredado sandbox. No envíe permissions y sandbox juntos. Use permissionProfile/list con el cwd del proyecto para detectar los perfiles disponibles y si los requisitos administrados permiten cada uno.

thread.sessionId identifica la raíz actual del árbol de sesiones activas. Los hilos raíz usan su propio id de hilo como id de sesión; los hilos bifurcados conservan el id de sesión de la raíz de la que proceden. Los clientes deben leer el id de sesión de thread.sessionId en lugar de derivarlo del id de hilo.

Para continuar una sesión almacenada, llame a thread/resume con el thread.id que registró anteriormente. La forma de la respuesta coincide con thread/start. También puede pasar las mismas sustituciones de configuración compatibles con thread/start, como personality:

{ "method": "thread/resume", "id": 11, "params": {
  "threadId": "thr_123",
  "personality": "friendly"
} }
{ "id": 11, "result": { "thread": { "id": "thr_123", "name": "Bug bash notes", "ephemeral": false } } }

Reanudar un hilo no actualiza thread.updatedAt (ni la hora de modificación del archivo de rollout) por sí solo. La marca de tiempo se actualiza cuando se inicia un turno.

Si marca un servidor MCP habilitado como required en la configuración y ese servidor no logra inicializarse, thread/start y thread/resume fallan en lugar de continuar sin él.

dynamicTools en thread/start es un campo experimental (requiere capabilities.experimentalApi = true). Codex conserva estas herramientas dinámicas en los metadatos del rollout del hilo y las restaura en thread/resume cuando no se proporcionan herramientas dinámicas nuevas.

Si reanuda con un modelo distinto del registrado en el rollout, Codex emite una advertencia y aplica una instrucción única de cambio de modelo en el siguiente turno.

Administrar el objetivo de un hilo

Use thread/goal/set, thread/goal/get y thread/goal/clear para administrar el mismo estado persistente del objetivo que muestra /goal en la TUI.

{ "method": "thread/goal/set", "id": 13, "params": {
  "threadId": "thr_123",
  "objective": "Finish the migration and keep tests green",
  "status": "active",
  "tokenBudget": 40000
} }
{ "id": 13, "result": { "goal": {
  "threadId": "thr_123",
  "objective": "Finish the migration and keep tests green",
  "status": "active",
  "tokenBudget": 40000,
  "tokensUsed": 0,
  "timeUsedSeconds": 0
} } }
{ "method": "thread/goal/updated", "params": {
  "threadId": "thr_123",
  "goal": {
    "threadId": "thr_123",
    "objective": "Finish the migration and keep tests green",
    "status": "active",
    "tokenBudget": 40000,
    "tokensUsed": 0,
    "timeUsedSeconds": 0
  }
} }

Los objetivos deben contener entre 1 y 4.000 caracteres. Proporcionar un objetivo nuevo reemplaza el objetivo y reinicia la contabilidad de uso. Proporcionar el objetivo actual que no se encuentra en un estado terminal u omitir objective actualiza el estado o el presupuesto de tokens sin alterar el historial de uso.

Para bifurcar una sesión almacenada, llame a thread/fork con el thread.id. Esto crea un nuevo id de hilo y emite una notificación thread/started para él. Pase lastTurnId para copiar el historial hasta ese turno, incluyéndolo, y omitir los turnos posteriores:

{ "method": "thread/fork", "id": 12, "params": { "threadId": "thr_123", "lastTurnId": "turn_456" } }
{ "id": 12, "result": { "thread": { "id": "thr_456", "sessionId": "thr_123", "forkedFromId": "thr_123" } } }
{ "method": "thread/started", "params": { "thread": { "id": "thr_456" } } }

App-server rechaza un lastTurnId en curso. Si omite el campo mientras el hilo de origen está en mitad de un turno, la bifurcación registra un marcador de interrupción en lugar de conservar un turno parcial sin marcar.

Pase ephemeral: true para crear una bifurcación en memoria sin añadirla a las listas de hilos almacenados:

{
  "method": "thread/fork",
  "id": 13,
  "params": {
    "threadId": "thr_123",
    "ephemeral": true
  }
}
{
  "id": 13,
  "result": {
    "thread": {
      "id": "thr_789",
      "sessionId": "thr_789",
      "forkedFromId": "thr_123",
      "ephemeral": true
    }
  }
}

Las bifurcaciones efímeras de hilos paginados también requieren excludeTurns: true. Ese campo es experimental y requiere capabilities.experimentalApi = true.

Cuando se ha establecido un título de hilo visible para el usuario, app-server rellena thread.name en las respuestas thread/list, thread/read, thread/resume, thread/unarchive y thread/rollback. thread/start y thread/fork pueden omitir name (o devolver null) hasta que se establezca un título posteriormente.

Leer un hilo almacenado (sin reanudarlo)

Use thread/read cuando quiera obtener los datos de un hilo almacenado, pero no quiera reanudar el hilo ni suscribirse a sus eventos.

includeTurns: cuando es true, la respuesta incluye los turnos del hilo; cuando es false o se omite, solo se obtiene el resumen del hilo.
Los objetos thread devueltos incluyen el valor de ejecución status (notLoaded, idle, systemError o active con activeFlags).

{ "method": "thread/read", "id": 19, "params": { "threadId": "thr_123", "includeTurns": true } }
{ "id": 19, "result": { "thread": { "id": "thr_123", "name": "Bug bash notes", "ephemeral": false, "status": { "type": "notLoaded" }, "turns": [] } } }

A diferencia de thread/resume, thread/read no carga el hilo en memoria ni emite thread/started.

Enumerar los turnos de un hilo

thread/turns/list es experimental. Úselo para paginar el historial de turnos de un hilo almacenado sin reanudarlo. De forma predeterminada, los resultados se ordenan del más reciente al más antiguo para que los clientes puedan obtener turnos anteriores mediante nextCursor. La respuesta también incluye backwardsCursor; páselo como cursor con sortDirection: "asc" para obtener turnos más recientes que el primer elemento de la página anterior.

itemsView controla cuántos datos de los elementos de los turnos incluye la respuesta:

notLoaded omite los elementos.
summary devuelve datos resumidos de los elementos y es el valor predeterminado cuando se omite.
full devuelve todos los datos de los elementos.

{ "method": "thread/turns/list", "id": 20, "params": {
  "threadId": "thr_123",
  "limit": 50,
  "sortDirection": "desc",
  "itemsView": "summary"
} }
{ "id": 20, "result": {
  "data": [],
  "nextCursor": "older-turns-cursor-or-null",
  "backwardsCursor": "newer-turns-cursor-or-null"
} }

thread/items/list también es experimental. Pagina los elementos persistentes sin reanudar el hilo. Pase turnId para restringir los resultados a un turno u omítalo para paginar elementos de todo el hilo. El almacén de hilos activo debe admitir la paginación de elementos; de lo contrario, el servidor devuelve un error de método no compatible.

Enumerar hilos (con paginación y filtros)

thread/list permite mostrar una interfaz de historial. De forma predeterminada, los resultados se ordenan del más reciente al más antiguo según createdAt. Los filtros se aplican antes de la paginación. Pase cualquier combinación de:

cursor: cadena opaca de una respuesta anterior; omítala para la primera página.
limit: el servidor usa de forma predeterminada un tamaño de página razonable si no se establece.
sortKey: created_at (predeterminado), updated_at o recency_at.
sortDirection: desc (predeterminado) o asc.
modelProviders: restringe los resultados a proveedores específicos; si no se establece, es nulo o es una matriz vacía, se incluyen todos los proveedores.
sourceKinds: restringe los resultados a orígenes de hilo específicos. Cuando se omite o es [], el servidor usa de forma predeterminada solo los orígenes interactivos: cli y vscode.
archived: cuando es true, enumera únicamente los hilos archivados. Cuando es false o se omite, enumera los hilos no archivados (valor predeterminado).
isPinned: cuando se proporciona, solo devuelve hilos cuyo estado persistente de fijación coincide. Omítalo para devolver hilos fijados y no fijados.
cwd: restringe los resultados a los hilos cuyo directorio de trabajo actual de la sesión coincide exactamente con esta ruta o con una de las rutas de una matriz. Las rutas relativas se resuelven a partir del directorio de trabajo del proceso de app-server.
useStateDbOnly: cuando es true, devuelve los resultados de la base de datos de estado sin examinar los registros JSONL de los hilos para reparar los metadatos. Omítalo o pase false para usar el comportamiento predeterminado de examen y reparación.
searchTerm: restringe los resultados a los hilos cuyo título extraído contiene este fragmento de texto que distingue entre mayúsculas y minúsculas.
parentThreadId: restringe los resultados a los hilos secundarios directos del hilo especificado. Este filtro es experimental y requiere capabilities.experimentalApi = true.
ancestorThreadId: restringe los resultados a los descendientes generados del hilo especificado a cualquier profundidad. Este filtro es experimental y requiere capabilities.experimentalApi = true; no lo combine con parentThreadId.

sourceKinds acepta los siguientes valores:

cli
vscode
exec
appServer
subAgent
subAgentReview
subAgentCompact
subAgentThreadSpawn
subAgentOther
unknown

Ejemplo:

{ "method": "thread/list", "id": 20, "params": {
  "cursor": null,
  "limit": 25,
  "sortKey": "created_at"
} }
{ "id": 20, "result": {
  "data": [
    { "id": "thr_a", "preview": "Create a TUI", "ephemeral": false, "isPinned": true, "modelProvider": "openai", "createdAt": 1730831111, "updatedAt": 1730831111, "name": "TUI prototype", "status": { "type": "notLoaded" } },
    { "id": "thr_b", "preview": "Fix tests", "ephemeral": false, "isPinned": false, "modelProvider": "openai", "createdAt": 1730750000, "updatedAt": 1730750000, "status": { "type": "notLoaded" } }
  ],
  "nextCursor": "opaque-token-or-null"
} }

Cuando nextCursor es null, ha llegado a la última página.

Actualizar los metadatos almacenados de un hilo

Use thread/metadata/update para modificar los metadatos almacenados de un hilo sin reanudar el hilo. Establezca isPinned para fijar o dejar de fijar el hilo, o actualice gitInfo para cambiar los metadatos Git persistentes. Los campos omitidos no cambian; un valor null explícito borra un valor almacenado de los metadatos Git.

{ "method": "thread/metadata/update", "id": 21, "params": {
  "threadId": "thr_123",
  "isPinned": true,
  "gitInfo": { "branch": "feature/sidebar-pr" }
} }
{ "id": 21, "result": {
  "thread": {
    "id": "thr_123",
    "isPinned": true,
    "gitInfo": { "sha": null, "branch": "feature/sidebar-pr", "originUrl": null }
  }
} }

Seguir los cambios de estado de los hilos

thread/status/changed se emite cada vez que cambia el estado de ejecución de un hilo cargado. La carga útil incluye threadId y el nuevo status.

{
  "method": "thread/status/changed",
  "params": {
    "threadId": "thr_123",
    "status": { "type": "active", "activeFlags": ["waitingOnApproval"] }
  }
}

Enumerar los hilos cargados

thread/loaded/list devuelve los id de los hilos cargados actualmente en memoria.

{ "method": "thread/loaded/list", "id": 21 }
{ "id": 21, "result": { "data": ["thr_123", "thr_456"] } }

Cancelar la suscripción a un hilo cargado

thread/unsubscribe elimina la suscripción de la conexión actual a un hilo. El estado de la respuesta es uno de los siguientes:

unsubscribed cuando la conexión estaba suscrita y ahora se ha eliminado.
notSubscribed cuando la conexión no estaba suscrita a ese hilo.
notLoaded cuando el hilo no está cargado.

Si era el último suscriptor, el servidor mantiene cargado el hilo hasta que no tenga suscriptores ni actividad durante 30 minutos. Cuando vence el periodo de gracia, app-server descarga el hilo y emite una transición thread/status/changed a notLoaded, además de thread/closed.

{ "method": "thread/unsubscribe", "id": 22, "params": { "threadId": "thr_123" } }
{ "id": 22, "result": { "status": "unsubscribed" } }

Si el hilo vence posteriormente:

{ "method": "thread/status/changed", "params": {
    "threadId": "thr_123",
    "status": { "type": "notLoaded" }
} }
{ "method": "thread/closed", "params": { "threadId": "thr_123" } }

Archivar un hilo

Use thread/archive para mover el registro persistente del hilo (almacenado como archivo JSONL en el disco) al directorio de sesiones archivadas. Al archivar un hilo, también se intenta archivar los hilos descendientes generados que aún no estén archivados.

{ "method": "thread/archive", "id": 22, "params": { "threadId": "thr_b" } }
{ "id": 22, "result": {} }
{ "method": "thread/archived", "params": { "threadId": "thr_b" } }
{ "method": "thread/archived", "params": { "threadId": "thr_child" } }

Los hilos archivados no aparecerán en futuras llamadas a thread/list, a menos que pases archived: true. El servidor emite una notificación thread/archived por cada hilo que archiva realmente; si no se puede archivar un descendiente generado, la solicitud puede completarse correctamente sin una notificación de archivado para ese descendiente.

Eliminar un hilo

Usa thread/delete para eliminar permanentemente un hilo activo o archivado persistente y sus hilos descendientes generados. El servidor elimina los archivos de rollout existentes y los metadatos asociados antes de devolver una respuesta correcta; los archivos de rollout ausentes se consideran ya eliminados. Los hilos raíz efímeros no se pueden eliminar.

{ "method": "thread/delete", "id": 23, "params": { "threadId": "thr_b" } }
{ "id": 23, "result": {} }
{ "method": "thread/deleted", "params": { "threadId": "thr_b" } }
{ "method": "thread/deleted", "params": { "threadId": "thr_child" } }

Desarchivar un hilo

Usa thread/unarchive para devolver el rollout de un hilo archivado al directorio de sesiones activas.

{ "method": "thread/unarchive", "id": 24, "params": { "threadId": "thr_b" } }
{ "id": 24, "result": { "thread": { "id": "thr_b", "name": "Bug bash notes" } } }
{ "method": "thread/unarchived", "params": { "threadId": "thr_b" } }

Activar la compactación de un hilo

Usa thread/compact/start para activar manualmente la compactación del historial de un hilo. La solicitud devuelve inmediatamente {}.

App-server emite el progreso mediante las notificaciones estándar turn/* y item/* en el mismo threadId, incluido el ciclo de vida de un elemento contextCompaction (item/started y después item/completed).

{ "method": "thread/compact/start", "id": 25, "params": { "threadId": "thr_b" } }
{ "id": 25, "result": {} }

Ejecutar un comando de shell en un hilo

Usa thread/shellCommand para los comandos de shell iniciados por el usuario que pertenecen a un hilo. La solicitud devuelve inmediatamente {} mientras el progreso se transmite mediante las notificaciones estándar turn/* y item/*.

Esta API se ejecuta fuera del entorno aislado con acceso completo y no hereda la política de entorno aislado del hilo. Los clientes solo deben exponerla para comandos iniciados explícitamente por el usuario.

Si el hilo ya tiene un turno activo, el comando se ejecuta como una acción auxiliar de ese turno y su salida formateada se inserta en el flujo de mensajes del turno. Si el hilo está inactivo, app-server inicia un turno independiente para el comando de shell.

{ "method": "thread/shellCommand", "id": 26, "params": { "threadId": "thr_b", "command": "git status --short" } }
{ "id": 26, "result": {} }

Limpiar terminales en segundo plano

Usa thread/backgroundTerminals/clean para detener todas las terminales en segundo plano en ejecución asociadas con un hilo. Este método es experimental y requiere capabilities.experimentalApi = true.

{ "method": "thread/backgroundTerminals/clean", "id": 27, "params": { "threadId": "thr_b" } }
{ "id": 27, "result": {} }

Usa thread/backgroundTerminals/list para inspeccionar las terminales en segundo plano en ejecución correspondientes a un hilo cargado. La solicitud admite la paginación estándar cursor y limit, y el processId devuelto es el id. del proceso de app-server. Este método es experimental y requiere capabilities.experimentalApi = true:

{ "method": "thread/backgroundTerminals/list", "id": 28, "params": { "threadId": "thr_b" } }
{ "id": 28, "result": { "data": [
  {
    "itemId": "item_456",
    "processId": "42",
    "command": "python3 -m http.server",
    "cwd": "/workspace",
    "osPid": null,
    "cpuPercent": null,
    "rssKb": null
  }
], "nextCursor": null } }

Usa thread/backgroundTerminals/terminate con ese processId para detener una terminal en segundo plano. Este método es experimental y requiere capabilities.experimentalApi = true:

{ "method": "thread/backgroundTerminals/terminate", "id": 29, "params": { "threadId": "thr_b", "processId": "42" } }
{ "id": 29, "result": { "terminated": true } }

Revertir turnos recientes

thread/rollback está obsoleto y se eliminará. Elimina las últimas numTurns entradas del contexto en memoria y conserva un marcador de reversión en el registro de rollout. El thread devuelto incluye turns rellenado después de la reversión.

{ "method": "thread/rollback", "id": 30, "params": { "threadId": "thr_b", "numTurns": 1 } }
{ "id": 30, "result": { "thread": { "id": "thr_b", "name": "Bug bash notes", "ephemeral": false } } }

Turnos

El campo input acepta una lista de elementos:

{ "type": "text", "text": "Explain this diff" }
{ "type": "image", "url": "https://.../design.png" }
{ "type": "localImage", "path": "/tmp/screenshot.png" }

Puedes reemplazar los ajustes de configuración en cada turno (modelo, esfuerzo, personalidad, cwd, política de entorno aislado y resumen). Cuando se especifican, estos ajustes se convierten en los valores predeterminados para los turnos posteriores del mismo hilo. outputSchema solo se aplica al turno actual. Para sandboxPolicy.type = "externalSandbox", configura networkAccess como restricted o enabled; para workspaceWrite, networkAccess sigue siendo un booleano.

Para turn/start.collaborationMode, settings.developer_instructions: null significa «usar las instrucciones integradas del modo seleccionado», no borrar las instrucciones del modo.

Acceso de lectura del entorno aislado (`ReadOnlyAccess`)

sandboxPolicy admite controles explícitos de acceso de lectura:

readOnly: access opcional ({ "type": "fullAccess" } de forma predeterminada o raíces restringidas).
workspaceWrite: readOnlyAccess opcional ({ "type": "fullAccess" } de forma predeterminada o raíces restringidas).

Estructura del acceso de lectura restringido:

{
  "type": "restricted",
  "includePlatformDefaults": true,
  "readableRoots": ["/Users/me/shared-read-only"]
}

En macOS, includePlatformDefaults: true añade una política Seatbelt predeterminada de la plataforma y seleccionada específicamente para las sesiones con lectura restringida. Esto mejora la compatibilidad de las herramientas sin permitir de forma generalizada todo /System.

Ejemplos:

{ "type": "readOnly", "access": { "type": "fullAccess" } }

{
  "type": "workspaceWrite",
  "writableRoots": ["/Users/me/project"],
  "readOnlyAccess": {
    "type": "restricted",
    "includePlatformDefaults": true,
    "readableRoots": ["/Users/me/shared-read-only"]
  },
  "networkAccess": false
}

Iniciar un turno

{ "method": "turn/start", "id": 30, "params": {
  "threadId": "thr_123",
  "input": [ { "type": "text", "text": "Run tests" } ],
  "cwd": "/Users/me/project",
  "approvalPolicy": "unlessTrusted",
  "sandboxPolicy": {
    "type": "workspaceWrite",
    "writableRoots": ["/Users/me/project"],
    "networkAccess": true
  },
  "model": "gpt-5.6-terra",
  "effort": "medium",
  "summary": "concise",
  "personality": "friendly",
  "outputSchema": {
    "type": "object",
    "properties": { "answer": { "type": "string" } },
    "required": ["answer"],
    "additionalProperties": false
  }
} }
{ "id": 30, "result": { "turn": { "id": "turn_456", "status": "inProgress", "items": [], "error": null } } }

Insertar elementos en un hilo

Usa thread/inject_items para añadir elementos preconstruidos de Responses API al historial de solicitudes de un hilo cargado sin iniciar un turno del usuario. Estos elementos se conservan en el rollout y se incluyen en las solicitudes posteriores al modelo.

{ "method": "thread/inject_items", "id": 31, "params": {
  "threadId": "thr_123",
  "items": [
    {
      "type": "message",
      "role": "assistant",
      "content": [{ "type": "output_text", "text": "Previously computed context." }]
    }
  ]
} }
{ "id": 31, "result": {} }

Orientar un turno activo

Usa turn/steer para añadir más entradas del usuario al turno activo en curso.

Incluye expectedTurnId; debe coincidir con el id. del turno activo.
La solicitud falla si no hay ningún turno activo en el hilo.
turn/steer no emite una nueva notificación turn/started.
turn/steer no acepta reemplazos a nivel de turno (model, cwd, sandboxPolicy o outputSchema).

{ "method": "turn/steer", "id": 32, "params": {
  "threadId": "thr_123",
  "input": [ { "type": "text", "text": "Actually focus on failing tests first." } ],
  "expectedTurnId": "turn_456"
} }
{ "id": 32, "result": { "turnId": "turn_456" } }

Iniciar un turno (invocar una habilidad)

Invoca explícitamente una habilidad incluyendo $<skill-name> en la entrada de texto y añadiendo junto a ella un elemento de entrada skill.

{ "method": "turn/start", "id": 33, "params": {
  "threadId": "thr_123",
  "input": [
    { "type": "text", "text": "$skill-creator Add a new skill for triaging flaky CI and include step-by-step usage." },
    { "type": "skill", "name": "skill-creator", "path": "/Users/me/.codex/skills/skill-creator/SKILL.md" }
  ]
} }
{ "id": 33, "result": { "turn": { "id": "turn_457", "status": "inProgress", "items": [], "error": null } } }

Interrumpir un turno

{ "method": "turn/interrupt", "id": 31, "params": { "threadId": "thr_123", "turnId": "turn_456" } }
{ "id": 31, "result": {} }

Si se completa correctamente, el turno finaliza con status: "interrupted".

Revisión

review/start ejecuta el revisor de Codex para un hilo y transmite los elementos de revisión. Los destinos incluyen:

uncommittedChanges
baseBranch (diferencias con respecto a una rama)
commit (revisar un commit específico)
custom (instrucciones de formato libre)

Usa delivery: "inline" (valor predeterminado) para ejecutar la revisión en el hilo existente o delivery: "detached" para bifurcar un nuevo hilo de revisión.

Ejemplo de solicitud/respuesta:

{ "method": "review/start", "id": 40, "params": {
  "threadId": "thr_123",
  "delivery": "inline",
  "target": { "type": "commit", "sha": "1234567deadbeef", "title": "Polish tui colors" }
} }
{ "id": 40, "result": {
  "turn": {
    "id": "turn_900",
    "status": "inProgress",
    "items": [
      { "type": "userMessage", "id": "turn_900", "content": [ { "type": "text", "text": "Review commit 1234567: Polish tui colors" } ] }
    ],
    "error": null
  },
  "reviewThreadId": "thr_123"
} }

Para una revisión separada, usa "delivery": "detached". La respuesta tiene la misma estructura, pero reviewThreadId será el id. del nuevo hilo de revisión (distinto del threadId original). El servidor también emite una notificación thread/started para ese nuevo hilo antes de transmitir el turno de revisión.

Codex transmite la notificación habitual turn/started seguida de un item/started con un elemento enteredReviewMode:

{
  "method": "item/started",
  "params": {
    "item": {
      "type": "enteredReviewMode",
      "id": "turn_900",
      "review": "current changes"
    }
  }
}

Cuando el revisor termina, el servidor emite item/started y item/completed, que contienen un elemento exitedReviewMode con el texto final de la revisión:

{
  "method": "item/completed",
  "params": {
    "item": {
      "type": "exitedReviewMode",
      "id": "turn_900",
      "review": "Looks solid overall..."
    }
  }
}

Usa esta notificación para representar la salida del revisor en tu cliente.

Ejecución de procesos

process/* es una API experimental y explícita para controlar procesos. Requiere capabilities.experimentalApi = true y se ejecuta fuera del entorno aislado de Codex. Úsala solo cuando tu cliente exponga intencionalmente el control de procesos locales sin un entorno aislado.

Inicia un proceso con process/spawn y proporciona un processHandle; después, usa ese identificador para las solicitudes de entrada estándar, cambio de tamaño y finalización. La salida se transmite mediante notificaciones process/outputDelta y la finalización se transmite mediante process/exited.

{ "method": "process/spawn", "id": 48, "params": {
  "command": ["python3", "-m", "pytest", "-q"],
  "processHandle": "pytest-1",
  "cwd": "/Users/me/project",
  "tty": true
} }
{ "id": 48, "result": {} }
{ "method": "process/outputDelta", "params": {
  "processHandle": "pytest-1",
  "stream": "stdout",
  "deltaBase64": "Li4u"
} }
{ "method": "process/exited", "params": {
  "processHandle": "pytest-1",
  "exitCode": 0
} }

Usa process/writeStdin con deltaBase64, closeStdin o ambos para enviar entradas. Usa process/resizePty para los eventos de cambio de tamaño de PTY y process/kill para finalizar un proceso en ejecución.

Ejecución de comandos

command/exec ejecuta un único comando (matriz argv) en el entorno aislado del servidor sin crear un hilo.

{ "method": "command/exec", "id": 50, "params": {
  "command": ["ls", "-la"],
  "cwd": "/Users/me/project",
  "sandboxPolicy": { "type": "workspaceWrite" },
  "timeoutMs": 10000
} }
{ "id": 50, "result": { "exitCode": 0, "stdout": "...", "stderr": "" } }

Usa sandboxPolicy.type = "externalSandbox" si ya ejecutas el proceso del servidor en un entorno aislado y quieres que Codex omita la aplicación de su propio entorno aislado. Para el modo de entorno aislado externo, configura networkAccess como restricted (valor predeterminado) o enabled. Para readOnly y workspaceWrite, usa la misma estructura opcional access / readOnlyAccess que se muestra arriba.

Notas:

El servidor rechaza las matrices command vacías.
sandboxPolicy acepta la misma estructura que usa turn/start (por ejemplo, dangerFullAccess, readOnly, workspaceWrite, externalSandbox).
Cuando se omite, timeoutMs recurre al valor predeterminado del servidor.
Configura tty: true para las sesiones respaldadas por PTY y usa processId cuando tengas previsto continuar con command/exec/write, command/exec/resize o command/exec/terminate.
Configura streamStdoutStderr: true para recibir notificaciones command/exec/outputDelta mientras se ejecuta el comando.

Leer los requisitos administrativos (`configRequirements/read`)

Usa configRequirements/read para inspeccionar los requisitos administrativos efectivos cargados desde requirements.toml o MDM, o desde ambos.

{ "method": "configRequirements/read", "id": 52, "params": {} }
{ "id": 52, "result": {
  "requirements": {
    "allowedApprovalPolicies": ["onRequest", "unlessTrusted"],
    "allowedSandboxModes": ["readOnly", "workspaceWrite"],
    "featureRequirements": {
      "personality": true,
      "unified_exec": false
    },
    "network": {
      "enabled": true,
      "allowedDomains": ["api.openai.com"],
      "allowUnixSockets": ["/tmp/example.sock"],
      "dangerouslyAllowAllUnixSockets": false
    }
  }
} }

result.requirements es null cuando no hay requisitos configurados. Consulta la documentación sobre requirements.toml para obtener información sobre las claves y los valores admitidos.

Configuración del entorno aislado de Windows (`windowsSandbox/setupStart`)

Los clientes personalizados de Windows pueden activar la configuración del entorno aislado de forma asíncrona en lugar de bloquear las comprobaciones de inicio.

{ "method": "windowsSandbox/setupStart", "id": 53, "params": { "mode": "elevated" } }
{ "id": 53, "result": { "started": true } }

App-server inicia la configuración en segundo plano y posteriormente emite una notificación de finalización:

{
  "method": "windowsSandbox/setupCompleted",
  "params": { "mode": "elevated", "success": true, "error": null }
}

Modos:

elevated - ejecuta la ruta de configuración con privilegios elevados del entorno aislado de Windows.
unelevated - ejecuta la ruta heredada de configuración/comprobación previa.

Sistema de archivos

Las API v2 del sistema de archivos operan sobre rutas absolutas. Usa fs/watch cuando un cliente necesite invalidar el estado de la interfaz de usuario después de que cambie un archivo o directorio.

{ "method": "fs/watch", "id": 54, "params": {
  "watchId": "0195ec6b-1d6f-7c2e-8c7a-56f2c4a8b9d1",
  "path": "/Users/me/project/.git/HEAD"
} }
{ "id": 54, "result": { "path": "/Users/me/project/.git/HEAD" } }
{ "method": "fs/changed", "params": {
  "watchId": "0195ec6b-1d6f-7c2e-8c7a-56f2c4a8b9d1",
  "changedPaths": ["/Users/me/project/.git/HEAD"]
} }
{ "method": "fs/unwatch", "id": 55, "params": {
  "watchId": "0195ec6b-1d6f-7c2e-8c7a-56f2c4a8b9d1"
} }
{ "id": 55, "result": {} }

La supervisión de un archivo emite fs/changed para la ruta de ese archivo, incluidas las actualizaciones realizadas mediante operaciones de sustitución o cambio de nombre.

Eventos

Las notificaciones de eventos son el flujo iniciado por el servidor para los ciclos de vida de los hilos, los turnos y los elementos que contienen. Después de iniciar o reanudar un hilo, continúa leyendo el flujo de transporte activo para recibir las notificaciones thread/started, thread/archived, thread/unarchived, thread/closed, thread/status/changed, turn/*, item/* y serverRequest/resolved.

Exclusión voluntaria de notificaciones

Los clientes pueden suprimir notificaciones específicas por conexión enviando nombres de métodos exactos en initialize.params.capabilities.optOutNotificationMethods.

Solo coincidencias exactas: item/agentMessage/delta suprime únicamente ese método.
Los nombres de métodos desconocidos se ignoran.
Se aplica a las notificaciones thread/*, turn/*, item/* y otras notificaciones v2 relacionadas.
No se aplica a solicitudes, respuestas ni errores.

Eventos de búsqueda aproximada de archivos (experimental)

La API de sesión de búsqueda aproximada de archivos emite notificaciones para cada consulta:

fuzzyFileSearch/sessionUpdated - { sessionId, query, files } con las coincidencias actuales de la consulta activa.
fuzzyFileSearch/sessionCompleted - { sessionId } cuando terminan la indexación y la búsqueda de coincidencias de esa consulta.

Eventos de advertencia

configWarning - { summary, details?, path?, range? } para problemas recuperables de configuración o inicialización.
warning - { threadId?, message } para advertencias de tiempo de ejecución no fatales.

Eventos de configuración del entorno aislado de Windows

windowsSandbox/setupCompleted - { mode, success, error } emitido después de que finalice una solicitud windowsSandbox/setupStart.

Eventos de turno

turn/started - { turn } con el id. del turno, un items vacío y status: "inProgress".
turn/completed - { turn }, donde turn.status es completed, interrupted o failed; los errores incluyen { error: { message, codexErrorInfo?, additionalDetails? } }.
turn/diff/updated - { threadId, turnId, diff } con la última diferencia unificada acumulada de todos los cambios de archivos del turno.
turn/plan/updated - { turnId, explanation?, plan } cada vez que el agente comparte o cambia su plan; cada entrada plan es { step, status } con status en pending, inProgress o completed.
hook/started y hook/completed - { threadId, turnId?, run } cuando se inicia un enlace del ciclo de vida y cuando está disponible el resumen final de su ejecución.
model/safetyBuffering/updated - { threadId, turnId, model, useCases, reasons, showBufferingUi, fasterModel } cuando una respuesta entra en un búfer de seguridad transitorio.
model/rerouted - { threadId, turnId, fromModel, toModel, reason } cuando el servicio dirige una solicitud a otro modelo.
model/verification - { threadId, turnId, verifications } cuando el servicio requiere una verificación adicional de la cuenta.
thread/tokenUsage/updated - actualizaciones de uso del hilo activo.

turn/diff/updated y turn/plan/updated incluyen actualmente matrices items vacías incluso cuando se transmiten eventos de elementos. Usa las notificaciones item/* como fuente de referencia para los elementos del turno.

Elementos

ThreadItem es la unión etiquetada incluida en las respuestas de los turnos y en las notificaciones item/*. Entre los tipos de elementos comunes se incluyen:

userMessage - {id, content}, donde content es una lista de entradas del usuario (text, image o localImage).
agentMessage - {id, text, phase?} que contiene la respuesta acumulada del agente. Cuando está presente, phase usa los valores de protocolo de Responses API (commentary, final_answer).
plan - {id, text} que contiene el texto del plan propuesto en el modo de planificación. Considera definitivo el último elemento plan de item/completed.
reasoning - {id, summary, content}, donde summary contiene los resúmenes de razonamiento transmitidos y content contiene los bloques de razonamiento sin procesar.
commandExecution - {id, command, cwd, status, commandActions, aggregatedOutput?, exitCode?, durationMs?}.
fileChange - {id, changes, status} que describe las modificaciones propuestas; changes enumera {path, kind, diff}.
mcpToolCall - {id, server, tool, status, arguments, appContext?, pluginId?, result?, error?}. Para aplicaciones MCP de confianza, appContext puede incluir connectorId, linkId, resourceUri, appName, templateId y el conector estable actionName. Los elementos antiguos conservados pueden omitir los metadatos más recientes. Usa appContext.resourceUri en lugar del mcpAppResourceUri obsoleto de nivel superior.
dynamicToolCall - {id, tool, arguments, status, contentItems?, success?, durationMs?} para invocaciones de herramientas dinámicas ejecutadas por el cliente.
collabToolCall - {id, tool, status, senderThreadId, receiverThreadId?, newThreadId?, prompt?, agentStatus?}.
webSearch - {id, query, action?} para las solicitudes de búsqueda web realizadas por el agente.
imageView - {id, path} emitido cuando el agente invoca la herramienta de visualización de imágenes.
enteredReviewMode - {id, review} enviado cuando se inicia el revisor.
exitedReviewMode - {id, review} emitido cuando finaliza el revisor.
contextCompaction - {id} emitido cuando Codex compacta el historial de la conversación.

Para webSearch.action, la acción type puede ser search (query?, queries?), openPage (url?) o findInPage (url?, pattern?).

App-server considera obsoleta la notificación heredada thread/compacted; usa en su lugar el elemento contextCompaction.

Todos los elementos emiten dos eventos compartidos del ciclo de vida:

item/started - emite el item completo cuando comienza una nueva unidad de trabajo; el item.id coincide con el itemId usado por los incrementos.
item/completed - envía el item final cuando termina el trabajo; considera este el estado definitivo.

Incrementos de elementos

item/agentMessage/delta - añade texto transmitido al mensaje del agente.
item/plan/delta - transmite el texto del plan propuesto. Es posible que el elemento plan final no coincida exactamente con los incrementos concatenados.
item/reasoning/summaryTextDelta - transmite resúmenes de razonamiento legibles; summaryIndex aumenta cuando se abre una nueva sección del resumen.
item/reasoning/summaryPartAdded - marca un límite entre las secciones del resumen de razonamiento.
item/reasoning/textDelta - transmite texto de razonamiento sin procesar (cuando el modelo lo admite).
item/commandExecution/outputDelta - transmite stdout/stderr para un comando; añade los incrementos en orden.
item/fileChange/outputDelta - notificación de compatibilidad obsoleta para la salida de texto heredada apply_patch. Las versiones actuales de app-server ya no la emiten; usa los elementos fileChange y turn/diff/updated en su lugar.

Errores

Si un turno falla, el servidor emite un evento error con { error: { message, codexErrorInfo?, additionalDetails? } } y después finaliza el turno con status: "failed". Cuando hay un estado HTTP del servicio ascendente disponible, aparece en codexErrorInfo.httpStatusCode.

Entre los valores comunes de codexErrorInfo se incluyen:

ContextWindowExceeded
UsageLimitExceeded
HttpConnectionFailed (errores 4xx/5xx del servicio ascendente)
ResponseStreamConnectionFailed
ResponseStreamDisconnected
ResponseTooManyFailedAttempts
BadRequest, Unauthorized, SandboxError, InternalServerError, Other

Cuando hay un estado HTTP del servicio ascendente disponible, el servidor lo reenvía en httpStatusCode en la variante codexErrorInfo correspondiente.

Aprobaciones

Según la configuración de Codex del usuario, la ejecución de comandos y los cambios de archivos pueden requerir aprobación. App-server envía al cliente una solicitud JSON-RPC iniciada por el servidor, y el cliente responde con una carga útil de decisión.

Decisiones sobre la ejecución de comandos: accept, acceptForSession, decline, cancel o { "acceptWithExecpolicyAmendment": { "execpolicy_amendment": ["cmd", "..."] } }.
Decisiones sobre cambios de archivos: accept, acceptForSession, decline, cancel.
Las solicitudes incluyen threadId y turnId; úsalos para limitar el estado de la interfaz de usuario a la conversación activa.
El servidor reanuda o rechaza el trabajo y finaliza el elemento con item/completed.

Aprobaciones de ejecución de comandos

Orden de los mensajes:

item/started muestra el elemento commandExecution pendiente con command, cwd y otros campos.
item/commandExecution/requestApproval incluye itemId, threadId, turnId, reason opcional, command opcional, cwd opcional, commandActions opcional, proposedExecpolicyAmendment opcional, networkApprovalContext opcional y availableDecisions opcional. Cuando es initialize.params.capabilities.experimentalApi = true, la carga útil también puede incluir el additionalPermissions experimental, que describe el acceso solicitado al entorno aislado para cada comando. Todas las rutas del sistema de archivos que contenga additionalPermissions son absolutas en el protocolo.
El cliente responde con una de las decisiones de aprobación de ejecución de comandos anteriores.
serverRequest/resolved confirma que la solicitud pendiente se ha respondido o borrado.
item/completed devuelve el elemento commandExecution final con status: completed | failed | declined.

Cuando networkApprovalContext está presente, la solicitud corresponde a acceso administrado a la red (no a una aprobación general de comandos de shell). El esquema v2 actual expone el host y el protocol de destino; los clientes deben mostrar una solicitud específica para la red y no depender de que command sea una vista previa del comando de shell comprensible para el usuario.

Codex agrupa por destino (host, protocolo y puerto) las solicitudes de aprobación de red simultáneas. Por lo tanto, app-server puede enviar una solicitud que desbloquee varias solicitudes en cola para el mismo destino, mientras que los distintos puertos del mismo host se tratan por separado.

Aprobaciones de cambios de archivos

Orden de los mensajes:

item/started emite un elemento fileChange con los changes y status: "inProgress" propuestos.
item/fileChange/requestApproval incluye itemId, threadId, turnId, reason opcional y grantRoot opcional.
El cliente responde con una de las decisiones de aprobación de cambios de archivos anteriores.
serverRequest/resolved confirma que la solicitud pendiente se ha respondido o borrado.
item/completed devuelve el elemento fileChange final con status: completed | failed | declined.

`tool/requestUserInput`

Cuando el cliente responde a item/tool/requestUserInput, app-server emite serverRequest/resolved con { threadId, requestId }. Si la solicitud pendiente se borra al iniciar, completar o interrumpir el turno antes de que el cliente responda, el servidor emite la misma notificación para esa limpieza.

Los parámetros de la solicitud incluyen autoResolutionMs como un tiempo de espera entero en milisegundos o null. Cuando está presente, los clientes host pueden resolver la solicitud automáticamente después de ese intervalo si el usuario no responde.

Solicitudes de permisos

La herramienta integrada request_permissions envía item/permissions/requestApproval con threadId, turnId, itemId, environmentId, cwd, reason opcional y los permisos solicitados de red o del sistema de archivos. Responde con permissions, que debe contener únicamente el subconjunto concedido. Configura scope como "session" para conservar la concesión en turnos posteriores de la misma sesión; omítelo o usa "turn" para una concesión limitada al turno. Los permisos que no se solicitaron se ignoran.

Solicitudes de obtención de datos del servidor MCP

Un servidor MCP puede interrumpir un turno con mcpServer/elicitation/request. La solicitud incluye threadId, un turnId opcional, serverName y una de estas estructuras de solicitud:

mode: "form" o mode: "openai/form", con message y requestedSchema.
mode: "url", con message, url y elicitationId.

Responde con action: "accept" y el content solicitado, o con action: "decline" o "cancel" y content: null. A continuación, app-server emite serverRequest/resolved. Para recibir la variante openai/form, suscríbete mediante initialize.params.capabilities.mcpServerOpenaiFormElicitation.

Llamadas a herramientas dinámicas (experimental)

dynamicTools en thread/start y el flujo correspondiente de solicitudes o respuestas item/tool/call son API experimentales.

Los nombres de las herramientas dinámicas y los espacios de nombres deben cumplir las restricciones de nombres de Responses API. Evita los nombres de espacios de nombres reservados que usan las herramientas integradas de Codex.

Cuando se invoca una herramienta dinámica durante un turno, app-server emite:

item/started con item.type = "dynamicToolCall", status = "inProgress", además de tool y arguments.
item/tool/call como solicitud del servidor al cliente.
La carga útil de respuesta del cliente con los elementos de contenido devueltos.
item/completed con item.type = "dynamicToolCall", el status final y cualquier valor contentItems o success devuelto.

Aprobaciones de llamadas a herramientas MCP (aplicaciones)

Las llamadas a herramientas de aplicaciones (conectores) también pueden requerir aprobación. Cuando la llamada a una herramienta de una aplicación tiene efectos secundarios, el servidor puede solicitar aprobación con tool/requestUserInput y opciones como Aceptar, Rechazar y Cancelar. Las anotaciones de herramientas destructivas siempre activan una aprobación, incluso cuando la herramienta también anuncia indicaciones de menor privilegio. Si el usuario rechaza o cancela, el elemento mcpToolCall relacionado finaliza con un error en lugar de ejecutar la herramienta.

Habilidades

Invoca una habilidad incluyendo $<skill-name> en la entrada de texto del usuario. Añade un elemento de entrada skill (recomendado) para que el servidor inserte las instrucciones completas de la habilidad en lugar de depender de que el modelo resuelva el nombre.

{
  "method": "turn/start",
  "id": 101,
  "params": {
    "threadId": "thread-1",
    "input": [
      {
        "type": "text",
        "text": "$skill-creator Add a new skill for triaging flaky CI."
      },
      {
        "type": "skill",
        "name": "skill-creator",
        "path": "/Users/me/.codex/skills/skill-creator/SKILL.md"
      }
    ]
  }
}

Si omites el elemento skill, el modelo seguirá analizando el marcador $<skill-name> e intentará localizar la habilidad, lo que puede aumentar la latencia.

Ejemplo:

$skill-creator Add a new skill for triaging flaky CI and include step-by-step usage.

Usa skills/list para obtener las habilidades disponibles (opcionalmente limitadas mediante cwds, con forceReload). También puedes incluir perCwdExtraUserRoots para explorar rutas absolutas adicionales como ámbito user para valores cwd específicos. App-server ignora las entradas cuyo cwd no esté presente en cwds. skills/list puede reutilizar un resultado almacenado en caché por cwd; configura forceReload: true para actualizarlo desde el disco. Cuando están presentes, el servidor lee interface y dependencies desde SKILL.json.

{ "method": "skills/list", "id": 25, "params": {
  "cwds": ["/Users/me/project", "/Users/me/other-project"],
  "forceReload": true,
  "perCwdExtraUserRoots": [
    {
      "cwd": "/Users/me/project",
      "extraUserRoots": ["/Users/me/shared-skills"]
    }
  ]
} }
{ "id": 25, "result": {
  "data": [{
    "cwd": "/Users/me/project",
    "skills": [
      {
        "name": "skill-creator",
        "description": "Create or update a Codex skill",
        "enabled": true,
        "interface": {
          "displayName": "Skill Creator",
          "shortDescription": "Create or update a Codex skill"
        },
        "dependencies": {
          "tools": [
            {
              "type": "env_var",
              "value": "GITHUB_TOKEN",
              "description": "GitHub API token"
            },
            {
              "type": "mcp",
              "value": "github",
              "transport": "streamable_http",
              "url": "https://example.com/mcp"
            }
          ]
        }
      }
    ],
    "errors": []
  }]
} }

El servidor también emite notificaciones skills/changed cuando cambian los archivos locales de habilidades supervisados. Considera esto una señal de invalidación y vuelve a ejecutar skills/list con tus parámetros actuales cuando sea necesario.

Para activar o desactivar una habilidad por ruta:

{
  "method": "skills/config/write",
  "id": 26,
  "params": {
    "path": "/Users/me/.codex/skills/skill-creator/SKILL.md",
    "enabled": false
  }
}

Aplicaciones (conectores)

Usa app/installed para leer la última instantánea confirmada del entorno de ejecución de las aplicaciones instaladas. Cada resultado incluye el id de la aplicación, runtimeName (o null), el estado efectivo de enabled y el estado de callable. Solo se puede llamar a una aplicación cuando la configuración efectiva la habilita y al menos una herramienta visible para el modelo cumple las políticas de la aplicación y la herramienta.

{
  "method": "app/installed",
  "id": 49,
  "params": {
    "threadId": "thread-1",
    "forceRefresh": false
  }
}
{
  "id": 49,
  "result": {
    "apps": [
      {
        "id": "demo-app",
        "runtimeName": "Demo App",
        "enabled": true,
        "callable": true
      }
    ]
  }
}

Omite threadId para usar la configuración global en lugar de la configuración de un hilo cargado. Configura forceRefresh: true para actualizar la instantánea del entorno de ejecución del conector antes de leerla. Cuando una política global o del espacio de trabajo bloquea el acceso a aplicaciones, una aplicación observada aún puede aparecer con enabled y callable configurados como false.

Usa app/list para obtener las aplicaciones disponibles. En la CLI/TUI, /apps es el selector visible para el usuario; en clientes personalizados, llama directamente a app/list. Cada entrada incluye tanto isAccessible (disponible para el usuario) como isEnabled (habilitada en config.toml), para que los clientes puedan distinguir la instalación o el acceso del estado habilitado local. Las entradas de aplicaciones también pueden incluir los campos opcionales branding, appMetadata y labels.

{ "method": "app/list", "id": 50, "params": {
  "cursor": null,
  "limit": 50,
  "threadId": "thread-1",
  "forceRefetch": false
} }
{ "id": 50, "result": {
  "data": [
    {
      "id": "demo-app",
      "name": "Demo App",
      "description": "Example connector for documentation.",
      "logoUrl": "https://example.com/demo-app.png",
      "logoUrlDark": null,
      "distributionChannel": null,
      "branding": null,
      "appMetadata": null,
      "labels": null,
      "installUrl": "https://chatgpt.com/apps/demo-app/demo-app",
      "isAccessible": true,
      "isEnabled": true
    }
  ],
  "nextCursor": null
} }

Si proporcionas threadId, la restricción por características de las aplicaciones (features.apps) usa la instantánea de configuración de ese hilo. Cuando se omite, app-server usa la configuración global más reciente.

app/list devuelve el resultado después de que se carguen tanto las aplicaciones accesibles como las aplicaciones del directorio. Configura forceRefetch: true para omitir las cachés de aplicaciones y obtener datos actualizados. Las entradas de la caché solo se sustituyen cuando las actualizaciones se completan correctamente.

El servidor también emite notificaciones app/list/updated cada vez que termina de cargarse cualquiera de las fuentes (aplicaciones accesibles o aplicaciones del directorio). Cada notificación incluye la última lista combinada de aplicaciones.

{
  "method": "app/list/updated",
  "params": {
    "data": [
      {
        "id": "demo-app",
        "name": "Demo App",
        "description": "Example connector for documentation.",
        "logoUrl": "https://example.com/demo-app.png",
        "logoUrlDark": null,
        "distributionChannel": null,
        "branding": null,
        "appMetadata": null,
        "labels": null,
        "installUrl": "https://chatgpt.com/apps/demo-app/demo-app",
        "isAccessible": true,
        "isEnabled": true
      }
    ]
  }
}

Usa app/read cuando ya conozcas los id. de las aplicaciones y necesites sus metadatos en lugar del estado del entorno de ejecución instalado. Pasa como máximo 100 appIds. El servidor conserva solo la primera aparición de cada id. repetido y mantiene ese orden tanto en apps como en missingAppIds. Las aplicaciones desconocidas o inaccesibles se devuelven en missingAppIds sin que falle toda la solicitud.

{
  "method": "app/read",
  "id": 52,
  "params": {
    "appIds": ["demo-app", "missing-app"],
    "includeTools": true
  }
}
{
  "id": 52,
  "result": {
    "apps": [
      {
        "id": "demo-app",
        "name": "Demo App",
        "description": "Example connector for documentation.",
        "iconUrl": null,
        "iconUrlDark": null,
        "distributionChannel": null,
        "installUrl": null,
        "pluginDisplayNames": [],
        "toolSummaries": [
          {
            "name": "search",
            "title": "Search",
            "description": "Search the app.",
            "isEnabled": true,
            "disabledReason": null,
            "isReadOnly": true
          }
        ]
      }
    ],
    "missingAppIds": ["missing-app"]
  }
}

Configura includeTools: true para solicitar resúmenes públicos de herramientas destinados únicamente a su visualización. La respuesta de metadatos no incluye el estado del entorno de ejecución de la aplicación instalada ni autoriza una llamada a una herramienta; usa app/installed para comprobar el estado efectivo de enabled y callable.

Invoca una aplicación insertando $<app-slug> en la entrada de texto y añadiendo un elemento de entrada mention con la ruta app://<id> (recomendado).

{
  "method": "turn/start",
  "id": 51,
  "params": {
    "threadId": "thread-1",
    "input": [
      {
        "type": "text",
        "text": "$demo-app Pull the latest updates from the team."
      },
      {
        "type": "mention",
        "name": "Demo App",
        "path": "app://demo-app"
      }
    ]
  }
}

Ejemplos de RPC de configuración para los ajustes de aplicaciones

Usa config/read, config/value/write y config/batchWrite para inspeccionar o actualizar los controles de aplicaciones en config.toml.

Lee la estructura efectiva de configuración de las aplicaciones (incluidos _default y los reemplazos por herramienta):

{ "method": "config/read", "id": 60, "params": { "includeLayers": false } }
{ "id": 60, "result": {
  "config": {
    "apps": {
      "_default": {
        "enabled": true,
        "destructive_enabled": true,
        "open_world_enabled": true,
        "approvals_reviewer": "user",
        "default_tools_approval_mode": "auto"
      },
      "google_drive": {
        "enabled": true,
        "destructive_enabled": false,
        "approvals_reviewer": "auto_review",
        "default_tools_approval_mode": "prompt",
        "tools": {
          "files/delete": { "enabled": false, "approval_mode": "approve" }
        }
      }
    }
  }
} }

apps._default.approvals_reviewer configura el revisor para todas las aplicaciones, a menos que un valor específico de una aplicación lo reemplace. Cuando ambos se omiten, la aplicación hereda el valor approvals_reviewer de nivel superior. apps._default.default_tools_approval_mode configura el modo de aprobación alternativo para las herramientas que no tengan un reemplazo específico de la aplicación o la herramienta. Los requisitos administrados del modo de aprobación prevalecen sobre los ajustes del modo de aprobación de las herramientas.

Actualiza el ajuste de una sola aplicación:

{
  "method": "config/value/write",
  "id": 61,
  "params": {
    "keyPath": "apps.google_drive.default_tools_approval_mode",
    "value": "prompt",
    "mergeStrategy": "replace"
  }
}

Aplica varias modificaciones de aplicaciones de forma atómica:

{
  "method": "config/batchWrite",
  "id": 62,
  "params": {
    "edits": [
      {
        "keyPath": "apps._default.destructive_enabled",
        "value": false,
        "mergeStrategy": "upsert"
      },
      {
        "keyPath": "apps.google_drive.tools.files/delete.approval_mode",
        "value": "approve",
        "mergeStrategy": "upsert"
      }
    ]
  }
}

Detectar e importar la configuración de agentes externos

Usa externalAgentConfig/detect para detectar artefactos de agentes externos que se puedan migrar y, después, pasa las entradas seleccionadas a externalAgentConfig/import.

Ejemplo de detección:

{ "method": "externalAgentConfig/detect", "id": 63, "params": {
  "includeHome": true,
  "cwds": ["/Users/me/project"]
} }
{ "id": 63, "result": {
  "items": [
    {
      "itemType": "AGENTS_MD",
      "description": "Import /Users/me/project/CLAUDE.md to /Users/me/project/AGENTS.md.",
      "cwd": "/Users/me/project"
    },
    {
      "itemType": "SKILLS",
      "description": "Copy skill folders from /Users/me/.claude/skills to /Users/me/.agents/skills.",
      "cwd": null
    }
  ]
} }

Ejemplo de importación:

{ "method": "externalAgentConfig/import", "id": 64, "params": {
  "migrationItems": [
    {
      "itemType": "AGENTS_MD",
      "description": "Import /Users/me/project/CLAUDE.md to /Users/me/project/AGENTS.md.",
      "cwd": "/Users/me/project"
    }
  ],
  "source": "claude-code"
} }
{ "id": 64, "result": { "importId": "8ae96ff3-3425-4f4c-8772-b6fd61502868" } }

El parámetro de importación opcional source de nivel superior identifica el producto que generó los elementos de migración seleccionados.

El servidor emite externalAgentConfig/import/progress a medida que se completan los tipos de elementos y externalAgentConfig/import/completed después de que finalicen todas las importaciones síncronas y en segundo plano. Estas notificaciones incluyen el mismo importId de la respuesta y itemTypeResults con successes y failures para cada tipo. La finalización puede producirse inmediatamente después de la respuesta o después de que terminen las importaciones remotas en segundo plano.

{ "method": "externalAgentConfig/import/progress", "params": {
  "importId": "8ae96ff3-3425-4f4c-8772-b6fd61502868",
  "itemTypeResults": [
    {
      "itemType": "AGENTS_MD",
      "successes": [
        { "itemType": "AGENTS_MD", "cwd": "/Users/me/project", "source": null, "target": "/Users/me/project/AGENTS.md" }
      ],
      "failures": []
    }
  ]
} }
{ "method": "externalAgentConfig/import/completed", "params": {
  "importId": "8ae96ff3-3425-4f4c-8772-b6fd61502868",
  "itemTypeResults": [
    {
      "itemType": "AGENTS_MD",
      "successes": [
        { "itemType": "AGENTS_MD", "cwd": "/Users/me/project", "source": null, "target": "/Users/me/project/AGENTS.md" }
      ],
      "failures": []
    }
  ]
} }

Lee las importaciones completadas anteriormente:

{ "method": "externalAgentConfig/import/readHistories", "id": 65 }
{ "id": 65, "result": { "data": [
  {
    "importId": "8ae96ff3-3425-4f4c-8772-b6fd61502868",
    "completedAtMs": 1781784000000,
    "successes": [
      { "itemType": "AGENTS_MD", "cwd": "/Users/me/project", "source": null, "target": "/Users/me/project/AGENTS.md" }
    ],
    "failures": []
  }
] } }

Los valores de itemType admitidos son AGENTS_MD, CONFIG, SKILLS, PLUGINS, MCP_SERVER_CONFIG, SUBAGENTS, HOOKS, COMMANDS y SESSIONS. Para los elementos PLUGINS, details.plugins enumera cada marketplaceName y la pluginNames que Codex puede intentar migrar. La detección solo devuelve elementos que aún requieren trabajo. Por ejemplo, Codex omite la migración de AGENTS cuando AGENTS.md ya existe y no está vacío, y las importaciones de habilidades no sobrescriben los directorios de habilidades existentes.

Al detectar plugins desde .claude/settings.json, Codex lee las fuentes de marketplace configuradas en extraKnownMarketplaces. Si enabledPlugins contiene plugins de claude-plugins-official, pero falta la fuente de marketplace, Codex infiere anthropics/claude-plugins-official como fuente.

Endpoints de autenticación

La superficie JSON-RPC de autenticación/cuenta expone métodos de solicitud/respuesta, además de notificaciones iniciadas por el servidor (sin id). Úsalos para determinar el estado de autenticación, iniciar o cancelar inicios de sesión, cerrar sesión, inspeccionar los límites de frecuencia de ChatGPT y notificar a los propietarios del espacio de trabajo que se han agotado los créditos o se han alcanzado los límites de uso.

Modos de autenticación

Codex admite estos modos de autenticación. account/updated.authMode muestra el modo activo e incluye el planType actual de ChatGPT cuando está disponible. account/read también proporciona detalles de la cuenta y el plan.

API key (apikey) - el llamador proporciona una OpenAI API key mediante type: "apiKey", y Codex la almacena para las solicitudes de API.
ChatGPT administrado (chatgpt) - Codex controla el flujo OAuth de ChatGPT, conserva los tokens y los actualiza automáticamente. Comienza con type: "chatgpt" para el flujo del navegador o con type: "chatgptDeviceCode" para el flujo de código de dispositivo.
Tokens externos de ChatGPT (chatgptAuthTokens) - función experimental destinada a aplicaciones host que ya controlan el ciclo de vida de autenticación de ChatGPT del usuario. La aplicación host proporciona directamente un accessToken, un chatgptAccountId y un chatgptPlanType opcional, y debe actualizar el token cuando se le solicite.
Amazon Bedrock - account/read muestra las cuentas de Bedrock como type: "amazonBedrock" e indica si las credenciales proceden de una API key de Bedrock administrada por Codex (credentialSource: "codexManaged") o de la cadena externa de credenciales de AWS (credentialSource: "awsManaged"). account/updated.authMode usa bedrockApiKey para las API key de Bedrock administradas por Codex.

Descripción general de la API

account/read - obtiene la información actual de la cuenta; opcionalmente, actualiza los tokens.
account/login/start - inicia el proceso de autenticación (apiKey, chatgpt, chatgptDeviceCode o el chatgptAuthTokens experimental).
account/login/completed (notificación) - se emite cuando termina un intento de inicio de sesión (correctamente o con un error).
account/login/cancel - cancela un inicio de sesión administrado de ChatGPT pendiente mediante loginId.
account/logout - cierra la sesión; activa account/updated.
account/updated (notificación) - se emite cada vez que cambia el modo de autenticación (authMode: apikey, chatgpt, chatgptAuthTokens, agentIdentity, personalAccessToken, bedrockApiKey o null) e incluye planType cuando está disponible.
account/chatgptAuthTokens/refresh (solicitud del servidor) - solicita nuevos tokens de ChatGPT administrados externamente después de un error de autorización.
account/rateLimits/read - obtiene los límites de frecuencia de ChatGPT.
account/rateLimits/updated (notificación) - se emite cada vez que cambian los límites de frecuencia de ChatGPT de un usuario.
account/sendAddCreditsNudgeEmail - solicita a ChatGPT que envíe un correo electrónico al propietario de un espacio de trabajo cuando se agoten los créditos o se alcance un límite de uso.
account/rateLimitResetCredit/consume - consume un restablecimiento de límite de frecuencia obtenido mediante un valor idempotencyKey proporcionado por el llamador.
account/usage/read - obtiene resúmenes de actividad de tokens y agrupaciones diarias de la cuenta de ChatGPT.
account/workspaceMessages/read - obtiene los mensajes activos del espacio de trabajo, incluidos los titulares de las notificaciones cuando estén disponibles.
mcpServer/oauthLogin/completed (notificación) - se emite después de que finalice un flujo mcpServer/oauth/login; la carga útil incluye { name, threadId, success, error? }. threadId puede ser null para los flujos OAuth limitados a una aplicación o un plugin.
mcpServer/startupStatus/updated (notificación) - se emite cuando cambia el estado de inicio de un servidor MCP configurado; la carga útil incluye { threadId, name, status, error, failureReason }. threadId es null para un inicio limitado a una aplicación. Si el inicio falla, failureReason: "reauthenticationRequired" significa que las credenciales OAuth almacenadas caducaron y no pudieron actualizarse, por lo que el cliente debe ofrecer la opción de volver a conectar el servidor.

1) Comprobar el estado de autenticación

Solicitud:

{ "method": "account/read", "id": 1, "params": { "refreshToken": false } }

Ejemplos de respuesta:

{ "id": 1, "result": { "account": null, "requiresOpenaiAuth": false } }

{ "id": 1, "result": { "account": null, "requiresOpenaiAuth": true } }

{
  "id": 1,
  "result": { "account": { "type": "apiKey" }, "requiresOpenaiAuth": true }
}

{
  "id": 1,
  "result": {
    "account": {
      "type": "amazonBedrock",
      "credentialSource": "codexManaged"
    },
    "requiresOpenaiAuth": false
  }
}

{
  "id": 1,
  "result": {
    "account": {
      "type": "amazonBedrock",
      "credentialSource": "awsManaged"
    },
    "requiresOpenaiAuth": false
  }
}

{
  "id": 1,
  "result": {
    "account": {
      "type": "chatgpt",
      "email": "user@example.com",
      "planType": "pro"
    },
    "requiresOpenaiAuth": true
  }
}

Notas sobre los campos:

refreshToken (booleano): configura true para forzar una actualización de tokens en el modo administrado de ChatGPT. En el modo de tokens externos (chatgptAuthTokens), app-server ignora este indicador.
email es null cuando la cuenta de ChatGPT no tiene una dirección de correo electrónico.
requiresOpenaiAuth refleja el proveedor activo; cuando es false, Codex puede ejecutarse sin credenciales de OpenAI.
Amazon Bedrock muestra credentialSource: "codexManaged" cuando usa una API key de Bedrock administrada por Codex. Muestra credentialSource: "awsManaged" para la ruta externa de credenciales de AWS. Esto identifica la fuente de credenciales seleccionada; no valida que la cadena de credenciales de AWS pueda resolver las credenciales.

2) Iniciar sesión con una API key

Envía:

   {
     "method": "account/login/start",
     "id": 2,
     "params": { "type": "apiKey", "apiKey": "sk-..." }
   }

Espera:

   { "id": 2, "result": { "type": "apiKey" } }

Notificaciones:

   {
     "method": "account/login/completed",
     "params": { "loginId": null, "success": true, "error": null }
   }

   {
     "method": "account/updated",
     "params": { "authMode": "apikey", "planType": null }
   }

3) Iniciar sesión con ChatGPT (flujo del navegador)

Inicia:

   {
     "method": "account/login/start",
     "id": 3,
     "params": {
       "type": "chatgpt",
       "useHostedLoginSuccessPage": true,
       "appBrand": "chatgpt"
     }
   }

De forma predeterminada, una devolución de llamada del navegador completada correctamente redirige a una página local de confirmación. Configura useHostedLoginSuccessPage: true para usar la página de confirmación alojada cuando no sea necesario configurar la organización. Con la confirmación alojada habilitada, appBrand puede ser "codex" o "chatgpt"; los valores omitidos o null usan de forma predeterminada "codex".

   {
     "id": 3,
     "result": {
       "type": "chatgpt",
       "loginId": "<uuid>",
       "authUrl": "https://chatgpt.com/...&redirect_uri=http%3A%2F%2Flocalhost%3A<port>%2Fauth%2Fcallback"
     }
   }

Abre authUrl en un navegador; app-server aloja la devolución de llamada local.
Espera las notificaciones:

   {
     "method": "account/login/completed",
     "params": { "loginId": "<uuid>", "success": true, "error": null }
   }

   {
     "method": "account/updated",
     "params": { "authMode": "chatgpt", "planType": "plus" }
   }

3b) Iniciar sesión con ChatGPT (flujo de código de dispositivo)

Usa este flujo cuando tu cliente controle el proceso de inicio de sesión o cuando una devolución de llamada del navegador sea poco fiable.

Inicia:

   {
     "method": "account/login/start",
     "id": 4,
     "params": { "type": "chatgptDeviceCode" }
   }

   {
     "id": 4,
     "result": {
       "type": "chatgptDeviceCode",
       "loginId": "<uuid>",
       "verificationUrl": "https://auth.openai.com/codex/device",
       "userCode": "ABCD-1234"
     }
   }

Muestra verificationUrl y userCode al usuario; el frontend controla la experiencia de usuario.
Espera las notificaciones:

   {
     "method": "account/login/completed",
     "params": { "loginId": "<uuid>", "success": true, "error": null }
   }

   {
     "method": "account/updated",
     "params": { "authMode": "chatgpt", "planType": "plus" }
   }

3c) Iniciar sesión con tokens de ChatGPT administrados externamente (`chatgptAuthTokens`)

Usa este modo experimental solo cuando una aplicación host controle el ciclo de vida de autenticación de ChatGPT del usuario y proporcione los tokens directamente. Los clientes deben configurar capabilities.experimentalApi = true durante initialize antes de usar este tipo de inicio de sesión.

Envía:

   {
     "method": "account/login/start",
     "id": 7,
     "params": {
       "type": "chatgptAuthTokens",
       "accessToken": "<jwt>",
       "chatgptAccountId": "org-123",
       "chatgptPlanType": "business"
     }
   }

Espera:

   { "id": 7, "result": { "type": "chatgptAuthTokens" } }

Notificaciones:

   {
     "method": "account/login/completed",
     "params": { "loginId": null, "success": true, "error": null }
   }

   {
     "method": "account/updated",
     "params": { "authMode": "chatgptAuthTokens", "planType": "business" }
   }

Cuando el servidor recibe un 401 Unauthorized, puede solicitar tokens actualizados a la aplicación host:

{
  "method": "account/chatgptAuthTokens/refresh",
  "id": 8,
  "params": { "reason": "unauthorized", "previousAccountId": "org-123" }
}
{ "id": 8, "result": { "accessToken": "<jwt>", "chatgptAccountId": "org-123", "chatgptPlanType": "business" } }

El servidor reintenta la solicitud original después de una respuesta de actualización correcta. El tiempo de espera de las solicitudes se agota después de unos 10 segundos.

4) Cancelar un inicio de sesión de ChatGPT

{ "method": "account/login/cancel", "id": 4, "params": { "loginId": "<uuid>" } }
{ "method": "account/login/completed", "params": { "loginId": "<uuid>", "success": false, "error": "..." } }

5) Cerrar sesión

{ "method": "account/logout", "id": 5 }
{ "id": 5, "result": {} }
{ "method": "account/updated", "params": { "authMode": null, "planType": null } }

6) Límites de frecuencia (ChatGPT)

{ "method": "account/rateLimits/read", "id": 6 }
{ "id": 6, "result": {
  "rateLimits": {
    "limitId": "codex",
    "limitName": null,
    "primary": { "usedPercent": 25, "windowDurationMins": 15, "resetsAt": 1730947200 },
    "secondary": null,
    "rateLimitReachedType": null
  },
  "rateLimitsByLimitId": {
    "codex": {
      "limitId": "codex",
      "limitName": null,
      "primary": { "usedPercent": 25, "windowDurationMins": 15, "resetsAt": 1730947200 },
      "secondary": null,
      "rateLimitReachedType": null
    },
    "codex_other": {
      "limitId": "codex_other",
      "limitName": "codex_other",
      "primary": { "usedPercent": 42, "windowDurationMins": 60, "resetsAt": 1730950800 },
      "secondary": null,
      "rateLimitReachedType": null
    }
  },
  "rateLimitResetCredits": {
    "availableCount": 2,
    "credits": [{
      "id": "RateLimitResetCredit_1",
      "resetType": "codexRateLimits",
      "status": "available",
      "grantedAt": 1781654400,
      "expiresAt": 1784246400,
      "title": "Rate-limit reset",
      "description": "Reset an eligible Codex rate-limit window."
    }]
  }
} }
{ "method": "account/rateLimits/updated", "params": {
  "rateLimits": {
    "limitId": "codex",
    "primary": { "usedPercent": 31, "windowDurationMins": 15, "resetsAt": 1730948100 }
  }
} }

Notas sobre los campos:

rateLimits es la vista de un único intervalo compatible con versiones anteriores.
rateLimitsByLimitId (cuando está presente) es la vista con varios intervalos, indexada por el limit_id medido (por ejemplo, codex).
limitId es el identificador del intervalo medido.
limitName es una etiqueta opcional del intervalo visible para el usuario.
usedPercent es el uso actual dentro del periodo de cuota.
windowDurationMins es la duración del periodo de cuota.
resetsAt es una marca de tiempo Unix (segundos) para el siguiente restablecimiento.
planType se incluye cuando el servidor devuelve el plan de ChatGPT asociado con un intervalo.
credits se incluye cuando el servidor devuelve información sobre los créditos restantes del espacio de trabajo.
rateLimitReachedType identifica el estado del límite clasificado por el servidor cuando se ha alcanzado alguno.
rateLimitResetCredits contiene la cantidad de restablecimientos obtenidos disponibles cuando el servicio la proporciona; de lo contrario, es null.
rateLimitResetCredits.credits es null cuando solo se conoce la cantidad. Una matriz vacía significa que el servicio obtuvo la información y no devolvió ningún crédito disponible. El servicio puede limitar las filas de información, por lo que availableCount es el valor definitivo.
Cada fila de información incluye un id opaco, resetType, status, grantedAt, expiresAt (que puede ser null), title (que puede ser null) y description (que puede ser null).
Obtén account/rateLimits/read después de consumir un restablecimiento.

7) Uso de tokens (ChatGPT)

Usa account/usage/read para obtener los campos de resumen de actividad de tokens de ChatGPT y las agrupaciones diarias opcionales.

{ "method": "account/usage/read", "id": 7 }
{ "id": 7, "result": {
  "summary": {
    "lifetimeTokens": 1234567,
    "peakDailyTokens": 45678,
    "longestRunningTurnSec": 540,
    "currentStreakDays": 8,
    "longestStreakDays": 14
  },
  "dailyUsageBuckets": [
    { "startDate": "2026-06-18", "tokens": 12345 }
  ]
} }

Notas sobre los campos:

Los valores de summary pueden ser null cuando el servicio no haya devuelto esa métrica.
dailyUsageBuckets puede ser null; cuando está presente, cada agrupación incluye startDate y tokens.
El endpoint requiere una autenticación respaldada por los servicios de Codex. Funcionan ChatGPT, los tokens externos de ChatGPT, la identidad del agente y la autenticación con un token de acceso personal; no funcionan la autenticación solo con una API key ni la autenticación de Bedrock.

8) Restablecimientos obtenidos del límite de frecuencia (ChatGPT)

Usa account/rateLimitResetCredit/consume para consumir un restablecimiento obtenido.

{ "method": "account/rateLimitResetCredit/consume", "id": 8, "params": { "idempotencyKey": "8ae96ff3-3425-4f4c-8772-b6fd61502868", "creditId": "RateLimitResetCredit_1" } }
{ "id": 8, "result": { "outcome": "reset" } }

Notas sobre los campos:

idempotencyKey no debe estar vacío. Usa un UUID para cada intento lógico de canje y reutiliza el mismo valor al reintentar ese intento.
creditId es opcional. Cuando se proporciona, debe ser un id. opaco no vacío de account/rateLimits/read. Cuando se omite, el servicio selecciona el siguiente crédito disponible.
reset significa que se consumió un crédito.
alreadyRedeemed significa que el mismo canje se completó anteriormente. Trátalo como un resultado idempotente correcto y actualiza los límites de la cuenta.
nothingToReset significa que no hay ningún periodo de límite de frecuencia apto para restablecerse.
noCredit significa que la cuenta no tiene créditos de restablecimiento obtenidos disponibles.
Obtén account/rateLimits/read después de consumir un restablecimiento, en lugar de deducir los periodos actualizados a partir de esta respuesta.

9) Notificar un límite al propietario de un espacio de trabajo

Usa account/sendAddCreditsNudgeEmail para solicitar a ChatGPT que envíe un correo electrónico al propietario de un espacio de trabajo cuando se agoten los créditos o se alcance un límite de uso.

{ "method": "account/sendAddCreditsNudgeEmail", "id": 9, "params": { "creditType": "credits" } }
{ "id": 9, "result": { "status": "sent" } }

Usa creditType: "credits" cuando se agoten los créditos del espacio de trabajo o creditType: "usage_limit" cuando se alcance el límite de uso del espacio de trabajo. Si ya se ha notificado recientemente al propietario, el estado de la respuesta es cooldown_active.

10) Mensajes del espacio de trabajo (ChatGPT)

Usa account/workspaceMessages/read para obtener los mensajes activos del espacio de trabajo actual, incluidos los titulares de las notificaciones cuando estén disponibles.

{ "method": "account/workspaceMessages/read", "id": 10 }
{ "id": 10, "result": { "featureEnabled": true, "messages": [
  { "messageId": "msg_123", "messageType": "headline", "messageBody": "Workspace maintenance starts at 5pm.", "createdAt": 1781395200, "archivedAt": null }
] } }

Conectar la interfaz de terminal de la CLI

Conectar un host remoto de Code Mode

Protocolo

Esquema de mensajes

Primeros pasos

Elementos fundamentales

Resumen del ciclo de vida

Inicialización

Adhesión a la API experimental

Resumen de la API

Modelos

Enumerar modelos (model/list)

Enumerar funciones experimentales (experimentalFeature/list)

Inspeccionar un entorno de ejecución (experimental)

Hilos

Iniciar o reanudar un hilo

Administrar el objetivo de un hilo

Leer un hilo almacenado (sin reanudarlo)

Enumerar los turnos de un hilo

Enumerar hilos (con paginación y filtros)

Actualizar los metadatos almacenados de un hilo

Seguir los cambios de estado de los hilos

Enumerar los hilos cargados

Cancelar la suscripción a un hilo cargado

Archivar un hilo

Eliminar un hilo

Desarchivar un hilo

Activar la compactación de un hilo

Ejecutar un comando de shell en un hilo

Limpiar terminales en segundo plano

Revertir turnos recientes

Turnos

Acceso de lectura del entorno aislado (ReadOnlyAccess)

Iniciar un turno

Insertar elementos en un hilo

Orientar un turno activo

Iniciar un turno (invocar una habilidad)

Interrumpir un turno

Revisión

Ejecución de procesos

Ejecución de comandos

Leer los requisitos administrativos (configRequirements/read)

Configuración del entorno aislado de Windows (windowsSandbox/setupStart)

Sistema de archivos

Eventos

Exclusión voluntaria de notificaciones

Eventos de búsqueda aproximada de archivos (experimental)

Eventos de advertencia

Eventos de configuración del entorno aislado de Windows

Eventos de turno

Elementos

Incrementos de elementos

Errores

Aprobaciones

Aprobaciones de ejecución de comandos

Aprobaciones de cambios de archivos

tool/requestUserInput

Solicitudes de permisos

Solicitudes de obtención de datos del servidor MCP

Llamadas a herramientas dinámicas (experimental)

Aprobaciones de llamadas a herramientas MCP (aplicaciones)

Habilidades

Aplicaciones (conectores)

Ejemplos de RPC de configuración para los ajustes de aplicaciones

Detectar e importar la configuración de agentes externos

Endpoints de autenticación

Modos de autenticación

Descripción general de la API

1) Comprobar el estado de autenticación

2) Iniciar sesión con una API key

3) Iniciar sesión con ChatGPT (flujo del navegador)

3b) Iniciar sesión con ChatGPT (flujo de código de dispositivo)

3c) Iniciar sesión con tokens de ChatGPT administrados externamente (chatgptAuthTokens)

4) Cancelar un inicio de sesión de ChatGPT

5) Cerrar sesión

6) Límites de frecuencia (ChatGPT)

7) Uso de tokens (ChatGPT)

8) Restablecimientos obtenidos del límite de frecuencia (ChatGPT)

9) Notificar un límite al propietario de un espacio de trabajo

10) Mensajes del espacio de trabajo (ChatGPT)

Enumerar modelos (`model/list`)

Enumerar funciones experimentales (`experimentalFeature/list`)

Acceso de lectura del entorno aislado (`ReadOnlyAccess`)

Leer los requisitos administrativos (`configRequirements/read`)

Configuración del entorno aislado de Windows (`windowsSandbox/setupStart`)

`tool/requestUserInput`

3c) Iniciar sesión con tokens de ChatGPT administrados externamente (`chatgptAuthTokens`)