Структурированный вывод Codex: надёжная передача JSON от агентов на VPS

Структурированный вывод Codex: надёжная передача JSON от агентов на VPS — Структурированный вывод Codex: exec, JSON Schema и отдельные журналы событий для проверяемых результатов на VPS. Корректный JSON ещё не доказывает успех.
15 нояб. 2026 г.5 мин чтения
Share with

Агент завершает ночную работу бодрым абзацем. А следующему скрипту нужно понять, пора ли отправить результат на проверку, остановиться из-за отсутствия учётных данных или повторить неудачное задание. Поиск слова «успех» в этом абзаце — не контракт передачи результата.

Мы используем структурированный вывод Codex, чтобы отделить удобный для чтения диалог от машиночитаемого результата. Здесь речь о границе передачи результата, а не о поддержании процесса: для этого начните с руководства по фоновым задачам.

Структурированный вывод Codex: события — не итоговый результат

Официальное руководство по неинтерактивному режиму описывает три разных механизма вывода:

МеханизмСодержимоеДля чего мы его используем
--jsonПоток JSONL с событиями выполненияДиагностика и история активности
--output-schemaКонтракт JSON Schema для итогового ответаСтабильные поля для следующего обработчика
-oИтоговое сообщение агента в отдельном файлеОтдельный артефакт передачи

Файл JSONL содержит много JSON-объектов, по одному на строку. Это не единый итоговый JSON-документ. Не передавайте весь журнал событий обработчику, который ожидает один объект результата.

Разделение событий выполнения, итогового JSON и проверки человеком

Схема ограничивает форму ответа, а не достоверность его содержимого. Агент может вернуть корректный JSON и при этом неверно понять падение теста. Учитывайте это при каждом последующем решении.

Запустите первого агента примерно за 3 минуты

Установите CLI Office Claws, подключите аккаунт Contabo и подписку Codex — агент получит собственный VPS и рабочее место в офисе.

curl -fsSL https://officeclaws.com/downloads/install.sh | sh

$4.99/мес + ваш собственный VPS в Contabo · ключи остаются в вашей связке ключей

Небольшой отчёт без записи в репозиторий на вашем VPS

Используйте доверенную рабочую копию Git на своём исполнителе с уже настроенной авторизацией Codex. Перед применением примера сверьтесь с codex exec --help для установленной версии. Это ручной shell-сценарий, а не встроенный планировщик Office Claws.

Создайте каталог артефактов вне рабочей копии, чтобы сгенерированные журналы не становились входными данными репозитория. В схеме намеренно мало полей: сводка, замечания и предложенные проверки. Мы не просим агента удостоверять безопасность собственной работы.

cd ~/work/product-api
umask 077
RUN_DIR=$(mktemp -d "$HOME/codex-report.XXXXXX")
cat > "$RUN_DIR/schema.json" <<'JSON'
{
  "type": "object",
  "properties": {
    "summary": { "type": "string" },
    "findings": {
      "type": "array",
      "items": { "type": "string" }
    },
    "suggested_checks": {
      "type": "array",
      "items": { "type": "string" }
    }
  },
  "required": ["summary", "findings", "suggested_checks"],
  "additionalProperties": false
}
JSON
 
git rev-parse HEAD > "$RUN_DIR/base-commit.txt"
codex --version > "$RUN_DIR/codex-version.txt"
if codex exec --sandbox read-only --json \
  --output-schema "$RUN_DIR/schema.json" \
  -o "$RUN_DIR/result.json" \
  "Inspect the repository for risky retry logic. Do not edit files. Report findings with file paths; suggest checks without running them." \
  > "$RUN_DIR/events.jsonl" 2> "$RUN_DIR/stderr.log"; then
  printf '0\n' > "$RUN_DIR/exit-code.txt"
else
  rc=$?
  printf '%s\n' "$rc" > "$RUN_DIR/exit-code.txt"
fi
printf 'Artifacts: %s\n' "$RUN_DIR"

Песочница только для чтения ограничивает запись, но не обеспечивает конфиденциальность. Запускайте агента только на коде, доступном авторизованной учётной записи, уберите ненужные секреты из окружения и проверьте конфигурацию проекта и подключённые инструменты до запуска. Никогда не включайте файлы авторизации в набор артефактов.

Отдельный файл кода завершения важен: управляющий процесс должен отличать сбой от успешного выполнения с замечаниями. Если используете тайм-аут или менеджер служб, сохраняйте и его состояние завершения. Постоянно работающий сервер не гарантирует, что Codex закончил ход.

Проверяйте артефакт до постановки на ревью

Наш контракт требует выполнения всех условий, а не просто наличия разбираемого файла:

  1. Сохранённый код завершения процесса равен нулю. Отсутствующий или ненулевой код означает сбой либо незавершённый запуск.
  2. result.json существует, не пуст и проходит проверку по той же схеме валидатором JSON Schema. Одной проверки синтаксиса JSON недостаточно.
  3. Сохранённый базовый коммит соответствует проверяемой рабочей копии. Отчёт по вчерашнему состоянию не служит доказательством для сегодняшней ветки.
  4. Ревьюер проверяет указанные пути и независимо запускает нужные тесты, прежде чем действовать по замечаниям.

Считайте строки внутри JSON недоверенным текстом. Никогда не подставляйте suggested_checks в shell и не превращайте предложенный моделью путь в неограниченное чтение файлов. Если позже автоматизируете этот сценарий, используйте список разрешённых команд и пути строго внутри репозитория.

СбойБезопасное следующее действие
Нет результата или схема не пройденаСохранить журналы; отметить попытку как незавершённую
Ошибка авторизации или лимит использованияДождаться оператора; не запускать частые повторы
Корректный JSON, слабые или неверные замечанияЗапросить ревью; формат не означает достоверность
Процесс прерван после внешних измененийПроверить фактическое состояние до повтора

Хотя этот пример работает только на чтение, будущие задания с записью требуют большей осторожности. Повтор агента не идемпотентен: предыдущая попытка уже могла изменить файлы или вызвать внешний инструмент. Создавайте новый каталог для каждой попытки, храните прежние свидетельства и проверяйте ветку перед продолжением. Другие сигналы состояния разобраны в руководстве по мониторингу.

Контракт вокруг постоянно доступного агента

Office Claws размещает агентов Codex на вашем собственном VPS Contabo и предоставляет CLI или пиксельное настольное приложение. Проверка схемы и обработка артефактов выше — ваши скрипты, а не обещание встроенного JSON-движка рабочих процессов. Сроки хранения, доступ, обновления и окончательное ревью остаются вашей ответственностью.

Слои затрат разделены: Office Claws стоит от $4.99/месяц за первого агента, VPS оплачивается отдельно, а поддерживаемый тариф ChatGPT даёт доступ к Codex в пределах своих лимитов. Постоянно включённый сервер не означает неограниченное использование модели. Перед расчётом очереди прочтите сравнение подписки и API.

Наша рекомендация: начните с одного отчёта только на чтение на одном исполнителе. Храните вместе события, итоговый JSON, статус завершения и идентификатор коммита. Добавляйте параллельных обработчиков только после отладки этого контракта; руководство по нескольким агентам Codex объясняет разделение рабочих каталогов.

Автор

Office Claws Team

Создаём будущее управления ИИ-агентами в Office Claws. Делимся опытом в области инфраструктуры, безопасности и удобства разработки.

Запустите первого агента примерно за 3 минуты

Установите CLI Office Claws, подключите аккаунт Contabo и подписку Codex — агент получит собственный VPS и рабочее место в офисе.

curl -fsSL https://officeclaws.com/downloads/install.sh | sh

$4.99/мес + ваш собственный VPS в Contabo · ключи остаются в вашей связке ключей