¿Cómo conectar Codex con modelos chinos? APIs compatibles con OpenAI y el enfoque de CodexBridge

CodexBridge es una herramienta local de puente cuyo objetivo es claro: exponer Codex CLI/SDK como un servicio HTTP compatible con OpenAI. Así, Codex deja de estar limitado al terminal y puede ser llamado desde OpenWebUI, Cherry Studio, scripts, sistemas de automatización o cualquier cliente compatible con OpenAI Chat Completions.

Sus endpoints principales son /v1/chat/completions y /v1/models. El primero gestiona conversaciones y admite respuestas normales y transmisión SSE. El segundo permite a los clientes descubrir modelos como si leyeran una lista de modelos estilo OpenAI. Para herramientas que ya soportan OpenAI API, normalmente basta con cambiar el base URL, la API key y el nombre del modelo.

Proyecto: https://github.com/begonia599/CodexBridge

Cuándo usarlo

CodexBridge encaja cuando quieres integrar Codex en clientes o flujos de trabajo existentes. Por ejemplo:

Seleccionar Codex directamente en OpenWebUI o Cherry Studio.
Llamar a Codex local desde curl, Python, Node.js u otros scripts.
Conectar un mismo frontend a OpenAI, Ollama, otras APIs compatibles y Codex.
Conservar los hilos locales, sandbox, directorio de trabajo y aprobaciones de Codex.
Ofrecer a herramientas internas una entrada unificada /v1/chat/completions.

No es un nuevo LLM ni un reemplazo completo de Codex CLI. Es más bien una capa adaptadora: Codex sigue siendo el motor aguas arriba, y el puente convierte solicitudes estilo OpenAI en entradas de conversación que Codex entiende.

Requisitos básicos

Antes de ejecutarlo necesitas:

Node.js 18 o superior.
Codex CLI instalado y con sesión iniciada.
npm, o pnpm / yarn si lo prefieres.

Despliegue básico desde código fuente:

1
2
3
4
5


git clone https://github.com/begonia599/CodexBridge
cd codexbridge
npm install
cp .env.example .env
cp .env .env.local

Luego edita .env o .env.local para definir la API key, modelo predeterminado, directorio de trabajo, modo sandbox, acceso de red y otras opciones.

Inicia el servicio HTTP:

1

npm run codex:server

El puerto predeterminado es 8080, configurable con PORT. Tras iniciar, el servicio expone:

1
2
3


GET /health
POST /v1/chat/completions
GET /v1/models

Modo de conversación CLI

Además del servicio HTTP, CodexBridge conserva una CLI ligera:

1

npm run codex:chat

Desde la CLI puedes escribir mensajes en lenguaje natural para conversar con Codex. Dos comandos útiles son:

/reset: crear un nuevo hilo de Codex.
/exit: salir de la CLI.

El ID del hilo actual se guarda en .codex_thread.json. Si este archivo sigue existiendo al iniciar la CLI de nuevo, puedes continuar la conversación anterior.

Ejemplo HTTP

Una solicitud mínima:

1
2
3
4


curl http://localhost:8080/v1/chat/completions \
  -H "content-type: application/json" \
  -H "authorization: Bearer 123321" \
  -d '{"model":"gpt-5-codex:medium","session_id":"demo","messages":[{"role":"user","content":"ls"}]}'

Puntos importantes:

El token de authorization debe coincidir con CODEX_BRIDGE_API_KEY.
model puede incluir nivel de razonamiento, por ejemplo gpt-5-codex:medium o gpt-5-codex:high.
session_id vincula la solicitud a una conversación y permite reutilizar el mismo hilo de Codex.

Para salida en streaming, añade stream: true:

1
2
3
4


curl -N http://localhost:8080/v1/chat/completions \
  -H "content-type: application/json" \
  -H "authorization: Bearer 123321" \
  -d '{"model":"gpt-5-codex:high","session_id":"stream","stream":true,"messages":[{"role":"user","content":"Explica paso a paso cómo crear un proyecto Node.js"}]}'

Para clientes que soportan respuestas en streaming de OpenAI, esta forma se siente más cercana a una conversación normal.

Persistencia de sesiones

Una función importante de CodexBridge es el mapeo de sesiones. La solicitud puede pasar un ID de sesión mediante estos campos:

session_id
conversation_id
thread_id
user

También puede pasarse por cabeceras:

x-session-id
session-id
x-conversation-id
x-thread-id
x-user-id

En producción conviene activar:

1

CODEX_REQUIRE_SESSION_ID=true

Así todas las solicitudes deben incluir un ID de sesión, evitando que distintos usuarios o ventanas de chat se mezclen en el mismo contexto temporal. El mapeo del puente se guarda en .codex_threads.json. Borrar este archivo restablece la relación del puente; los hilos propios de Codex siguen en ~/.codex/sessions.

Si CODEX_REQUIRE_SESSION_ID=false y la solicitud no incluye ID de sesión, el puente expande los messages actuales como una entrada de un solo uso para Codex. Sirve para llamadas temporales, pero no para conversaciones largas.

Entrada multimodal

CodexBridge admite bloques de contenido estilo OpenAI y convierte imágenes en entradas local_image utilizables por Codex.

Imagen remota:

1
2
3
4
5
6


{
  "type": "image_url",
  "image_url": {
    "url": "https://example.com/demo.png"
  }
}

Imagen local:

1
2
3
4


{
  "type": "local_image",
  "path": "./images/demo.png"
}

Los recursos remotos se descargan primero en un directorio temporal y se limpian al final del turno. En uso real, presta atención al tamaño del cuerpo de la solicitud, especialmente cuando envías imágenes en base64. Puede que necesites aumentar CODEX_JSON_LIMIT.

Salida estructurada

Si el cliente soporta response_format, CodexBridge puede mapearlo al outputSchema de Codex. Es útil cuando quieres que Codex devuelva una estructura JSON fija, como resultados de revisión, resúmenes, clasificación o informes de automatización.

Ejemplo mínimo:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28


{
  "model": "gpt-5-codex",
  "session_id": "lint",
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "name": "lint_report",
      "schema": {
        "type": "object",
        "properties": {
          "summary": { "type": "string" },
          "status": {
            "type": "string",
            "enum": ["ok", "action_required"]
          }
        },
        "required": ["summary", "status"],
        "additionalProperties": false
      }
    }
  },
  "messages": [
    {
      "role": "user",
      "content": "Revisa los problemas de lint en src/ y devuelve el resultado como JSON"
    }
  ]
}

type: "json_schema" debe incluir schema; de lo contrario, el servicio devuelve 400.

Variables de entorno clave

La configuración común puede agruparse así.

Servicio y autenticación:

1
2
3


PORT=8080
CODEX_BRIDGE_API_KEY=123321
CODEX_JSON_LIMIT=10mb

Modelo predeterminado:

1
2


CODEX_MODEL=gpt-5-codex
CODEX_REASONING=medium

Entorno de ejecución de Codex:

1
2
3
4


CODEX_WORKDIR=
CODEX_SANDBOX_MODE=read-only
CODEX_APPROVAL_POLICY=never
CODEX_SKIP_GIT_CHECK=true

Acceso de red:

1
2


CODEX_NETWORK_ACCESS=false
CODEX_WEB_SEARCH=false

Si solo lo usas para chat desde un frontend, es más seguro mantener la red desactivada por defecto. Activa estas opciones solo cuando Codex necesite ejecutar curl, git clone o búsqueda web.

Docker y scripts de instalación

El proyecto también ofrece despliegue con Docker para mantener el servicio en ejecución:

1
2


docker compose up -d
docker compose logs -f codexbridge

También hay un script de instalación para Linux:

1

curl -fsSL https://raw.githubusercontent.com/begonia599/CodexBridge/master/scripts/install.sh | bash

El script instala dependencias, clona o actualiza el repositorio, copia .env.example e inicia el servicio con Docker Compose. Requiere sudo, por lo que encaja mejor en un servidor limpio. Si la máquina ya tiene un entorno complejo de Node.js, Docker o Codex, revisa el script antes de ejecutarlo.

Problemas comunes

La solicitud devuelve 413

Normalmente el cuerpo es demasiado grande, a menudo por imágenes base64. Aumenta:

1

CODEX_JSON_LIMIT=20mb

La API key no es válida

Comprueba que la cabecera incluya:

1

Authorization: Bearer <tu CODEX_BRIDGE_API_KEY>

o usa x-api-key.

Codex informa una restricción de repositorio Git

Si el directorio de ejecución no es un repositorio confiable, Codex puede activar una verificación. Úsalo solo en entornos seguros:

1

CODEX_SKIP_GIT_CHECK=true

Restablecer conversaciones

El mapeo del puente está en .codex_threads.json, y los hilos propios de Codex están en ~/.codex/sessions. Detén el servicio y borra los archivos o directorios correspondientes para restablecerlos.

Recomendaciones

Para pruebas locales, empieza con la API key predeterminada y el sandbox read-only. Cuando OpenWebUI, Cherry Studio o tus scripts llamen al servicio correctamente, ajusta gradualmente CODEX_WORKDIR, CODEX_SANDBOX_MODE, CODEX_NETWORK_ACCESS y CODEX_APPROVAL_POLICY.

Si lo usarán varias personas, al menos:

Exige session_id.
Cambia la API key predeterminada.
Limita claramente el directorio de trabajo y los permisos del sandbox.

El valor de CodexBridge no está en tener muchas funciones, sino en colocar Codex dentro del ecosistema compatible con OpenAI. Si un cliente permite cambiar el base URL, puede tratar Codex como un modelo de chat normal y conservar al mismo tiempo sus hilos locales, sandbox y llamadas a herramientas.