# Подключение к очереди Codex CLI Рабочий адрес генератора — `https://codex-cli.wesslex.ru`. Ваше приложение отправляет промпт и модель, получает HTTP 202 и освобождает соединение. Когда задача завершится, генератор пришлёт итоговый текст или код ошибки на ваш HTTPS-обработчик. Ожидание сброса подписки может занять несколько дней. ## Подключить приложение 1. Подготовьте публичный HTTPS-маршрут для `POST` на порту 443. Пример приёмника приведён ниже. 2. Получите у владельца генератора `CODEX_JOBS_TOKEN` для отправки задач и независимый `CODEX_WEBHOOK_SECRET` для проверки вебхуков. Храните их на стороне сервера. Для каждого приложения выпускайте свою пару. 3. До отправки сохраните у себя постоянный `request_id` вместе с локальной задачей. Обработчик вебхуков должен находить задание по этому идентификатору, даже если вебхук опередил сохранение ответа HTTP 202. Пример запроса из shell с экспортированным токеном. Подставьте свой URL и выберите модель, доступную вашей подписке. ```bash curl --fail-with-body https://codex-cli.wesslex.ru/v1/jobs \ -H "Authorization: Bearer $CODEX_JOBS_TOKEN" \ -H 'Content-Type: application/json' \ --data '{ "request_id": "product-42-description-v1", "model": "gpt-6-luna", "prompt": "Напиши короткое описание букета из трёх белых роз.", "callback_url": "https://shop.example/hooks/codex" }' ``` Новая задача получает `202 {"job_id":"","status":"queued"}` после записи на диск. При обрыве связи повторите **все четыре поля без изменений**. Тот же токен и `request_id` вернут прежний `job_id` и текущий статус. Изменение любого поля с тем же идентификатором вернёт 409. Для новой редакции используйте новый идентификатор. Ключ действует до удаления записи, через 30 дней после успешной доставки. | Поле | Значение | | --- | --- | | `request_id` | 1–128 символов из латинских букв, цифр и `._:-`. Уникально в пределах приложения. | | `prompt` | Непустой текст до 64 000 символов. | | `model` | Точный ID модели. У каждой задачи один текстовый ответ. | | `callback_url` | Абсолютный публичный HTTPS URL на порту 443, до 2048 символов. Используйте ASCII-URL с percent-encoding при необходимости. При выпуске токена владелец может ограничить допустимые адреса точным списком. | HTTP 401 означает проблему с токеном, 422 — ошибку полей или адреса. HTTP 429 означает, что у приложения уже 1000 задач в работе или с неподтверждённой доставкой. Повторите позже с прежним `request_id`. При нехватке лимита самой подписки новые запросы по-прежнему получают 202. ## Принять результат Событие `job.succeeded` содержит текст в `result`. У `job.failed` в `result` приходит `null`, а в `error` — код причины, например `modelNotFound`, `timeout` или `generation_failed`. Остальные поля совпадают. ```json { "event_id": "b36371f8-b52f-41c0-a096-8c21f45dc221", "type": "job.succeeded", "job_id": "b36371f8-b52f-41c0-a096-8c21f45dc221", "request_id": "product-42-description-v1", "model": "gpt-6-luna", "status": "succeeded", "result": "Три белые розы с нежным ароматом.", "error": null, "finished_at": 1795343200 } ``` Генератор подписывает байты `.<исходное тело HTTP>` алгоритмом HMAC-SHA256. Ключ — строка `CODEX_WEBHOOK_SECRET` в UTF-8, включая все её символы. Заголовок `X-Webhook-Signature` имеет вид `sha256=`. Проверяйте подпись на исходных байтах до разбора JSON. Сверяйте время попытки с часами вашего сервера. Каждая повторная доставка получает свежую подпись и тот же `event_id`. Ниже минимальный приёмник на FastAPI. SQLite-файл должен находиться на постоянном диске приложения. Входящие события записываются до ответа 204. Фоновый обработчик приложения может выбирать их из этой таблицы и применять результат по `request_id`. ```python import hashlib import hmac import json import os import sqlite3 import time from contextlib import closing from fastapi import Depends, FastAPI, HTTPException, Request, Response app = FastAPI() secret = os.environ["CODEX_WEBHOOK_SECRET"].encode() inbox = os.environ["CODEX_INBOX_DB"] with closing(sqlite3.connect(inbox)) as db: db.execute("CREATE TABLE IF NOT EXISTS inbox (event_id TEXT PRIMARY KEY, payload BLOB NOT NULL)") async def signed_body(request: Request): body = await request.body() timestamp = request.headers.get("X-Webhook-Timestamp", "") if not timestamp.isascii() or not timestamp.isdigit() or len(timestamp) > 12: raise HTTPException(401) if abs(time.time() - int(timestamp)) > 300: raise HTTPException(401) signed = timestamp.encode() + b"." + body expected = "sha256=" + hmac.new(secret, signed, hashlib.sha256).hexdigest() actual = request.headers.get("X-Webhook-Signature", "").encode() if not hmac.compare_digest(expected.encode(), actual): raise HTTPException(401) return body @app.post("/hooks/codex") def callback(body: bytes = Depends(signed_body)): event = json.loads(body) with closing(sqlite3.connect(inbox, timeout=10)) as db, db: db.execute("INSERT INTO inbox VALUES (?, ?) ON CONFLICT(event_id) DO NOTHING", (event["event_id"], body)) return Response(status_code=204) ``` Любой ответ 2xx подтверждает доставку. При сетевой ошибке, тайм-ауте или другом HTTP-статусе генератор повторит POST через 10, 20, 40 секунд и далее с интервалом до часа до подтверждения. Перенаправления отключены. Повторы доставки используют сохранённый результат. При аварии самого генератора во время активного вызова CLI вычисление может повториться. Приложение должно один раз применить событие с данным `event_id`. ## Диагностика - `GET /v1/jobs/{job_id}` с токеном отправителя возвращает статус `queued`, `running`, `succeeded` или `failed`, затем `result`, `error` и состояние доставки `pending` или `delivered`. Поля `delivery_attempts` и `next_attempt` помогают разобрать недоступность получателя. Для повседневной обработки достаточно вебхука. - `GET /v1/limits` с токеном показывает общий снимок подписки. `windows.primary` и `windows.secondary` содержат `remaining_percent` и `resets_at`, если CLI сообщил эти окна. Время — Unix seconds UTC. `checked_at` относится к снимку, `retry_at` — к следующей проверке после паузы. Число будущих генераций зависит от размера заданий. - Новые клиенты получают очередь по кругу, задачи каждого клиента идут в порядке поступления. Одновременно работает одна генерация, включая старую интеграцию Ozon. Пока очередь свободна, генератор обновляет снимок раз в минуту. При исчерпании одного из окон он ждёт сброса всех исчерпанных окон, затем снова запрашивает состояние. При недоступности данных проверки повторяются раз в минуту, задания остаются на диске. Доставка готовых ответов продолжается независимо.