Guía práctica de codex-quota: uso local, web y de Docker con comandos CLI originales

Thu, 16 Apr 2026 18:13:04 +0800

Qué hace este proyecto

codex-quota es una herramienta liviana para verificar el uso de la cuota de ChatGPT Codex, con datos obtenidos de https://chatgpt.com/backend-api/wham/usage.

Características principales:

Admite consultas de una sola cuenta y de varias cuentas (account/*.auth.json).
Genera five_hour%, weekly%, weekly_reset y marca la fuente (network o cache).
Utiliza reintentos de retroceso exponencial para fallas temporales (408, 429, 5xx).
Incluye almacenamiento en caché local para reducir las solicitudes repetidas cuando la cuota ya está agotada.
Proporciona un panel web, API JSON y páginas de administración de archivos de autenticación.

Ventajas:

Ligero: se ejecuta con scripts simples y dependencias mínimas.
Práctico: admite puntos de entrada CLI y Web.
Implementable: funciona con Docker y Docker Compose.
Fácil de operar: incluye reintento, caché y soporte de actualización programada.

Prepare las credenciales de la cuenta primero

Cree archivos de credenciales en account/<name>.auth.json, por ejemplo:

{
  "tokens": {
    "access_token": "eyJ...",
    "account_id": "user-xxxxxxxx"
  }
}

Explicación:

La API de uso requiere access_token y account_id.
<nombre> en el nombre del archivo se utiliza como nombre de cuenta en la salida.

Uso de CLI local (conservar los comandos originales)

Instalar dependencias:

`1`	`pip install -r requirements.txt`

Explicación: instala las dependencias del proyecto.

Consultar todas las cuentas:

`1`	`python codex_quota.py`

Explicación: lee account/*.auth.json y genera un resumen de cuota para todas las cuentas.

Consulta una cuenta:

`1`	`python codex_quota.py your_account_name`

Explicación: solo consulta cuenta/nombre_de_cuenta.auth.json.

Forzar actualización (omitir caché):

`1`	`python codex_quota.py --refresh`

Explicación: ignora el caché local y recupera datos nuevos directamente.

Opciones CLI (alineadas con README)

account_name: nombre de cuenta opcional (sin .auth.json).
--account-dir: directorio de autenticación, cuenta predeterminada.
--chatgpt-url: punto final de API de cuota.
--raw-json: imprime el cuerpo completo de la respuesta JSON.
--raw-headers: imprime encabezados de respuesta.
--refresh: ignora el caché.
--retries: recuento de reintentos, valor predeterminado 3.
--retry-delay: retraso de reintento base en segundos, valor predeterminado 2.0.

Uso del panel web (conservar el comando original)

Iniciar el servicio:

`1`	`python codex_quota_service.py --host 0.0.0.0 --port 8081`

Explicación: inicia el servicio HTTP escuchando en el puerto 8081.

URL de acceso: http://localhost:8081

Opciones de servicio:

--host: dirección de enlace, predeterminado 0.0.0.0.
--port: puerto de servicio, predeterminado 8081.
--interval-segundos: intervalo de actualización programado, predeterminado 3600.
--account-dir: directorio de autenticación, cuenta predeterminada.
--state-file: ruta del archivo de estado, predeterminado <account-dir>/codex_quota_web_results.json.
--account-name: modo de cuenta única opcional.
--chatgpt-url: punto final de API de cuota.
--retries: recuento de reintentos.
--retry-delay: retraso de reintento base.
--refresh: ignora el caché CLI durante las ejecuciones programadas.

Puntos finales HTTP (para automatización)

GET /: página del panel de control.
GET /api/results: últimos resultados en JSON.
GET /refresh: activa la actualización inmediata y redirige a /.
GET /auth: enumera los archivos de autenticación.
GET /auth/new: formulario para crear un archivo de autenticación.
GET /auth/edit?name=<cuenta>: formulario para editar el archivo de autenticación.
POST /auth/save: crea/actualiza el archivo de autenticación.
POST /auth/delete: elimina el archivo de autenticación.

Uso de Docker (conservar los comandos originales)

Construir imagen:

`1`	`docker build -t codex-quota .`

Explicación: construye el proyecto actual como imagen codex-quota.

Ejecutar contenedor (mapa 8081):

`1`	`docker run --rm -p 8081:8081 -v ./account:/app/account codex-quota`

Explicación:

--rm: elimina el contenedor automáticamente después de salir.
-p 8081:8081: asigna el puerto del host al puerto del contenedor.
-v ./account:/app/account: monta las credenciales locales en el contenedor.

URL de acceso: http://localhost:8081

Uso de Docker Compose (conservar el comando original)

Inicio:

`1`	`docker compose up --build`

Explicación: cree e inicie servicios basados en docker-compose.yml.

URL de acceso: http://localhost:8081

Consejos de uso

Para escenarios de múltiples cuentas, use primero el Panel de control para una vista unificada y administración de autenticación.
Para alertas o automatización, prefiera GET /api/results.
No envíe valores reales de access_token a repositorios públicos.
Si ve muchas fallas temporales, aumente --retries y --retry-delay.

Seguimiento De Cuota on KnightLi Blog

Guía práctica de codex-quota: uso local, web y de Docker con comandos CLI originales

Qué hace este proyecto

Prepare las credenciales de la cuenta primero

Uso de CLI local (conservar los comandos originales)

Opciones CLI (alineadas con README)

Uso del panel web (conservar el comando original)

Puntos finales HTTP (para automatización)

Uso de Docker (conservar los comandos originales)

Uso de Docker Compose (conservar el comando original)

Consejos de uso