codex app-server — как встроить Codex в собственное приложение

Практическое руководство по codex app-server: двунаправленному JSON-RPC-интерфейсу, через который клиенты управляют агентным контуром Codex. Разберём выбор способа интеграции, запуск через stdio, протокол, потоки и ходы, подтверждения действий и проверку минимального клиента.

Содержание

1. Что такое Codex App Server
2. Что выбрать: App Server, SDK, exec или MCP
3. Запуск и транспорт
4. Формат протокола и генерация типов
5. Потоки, ходы и элементы
6. Основные методы и события
7. Подтверждения и sandbox
8. Минимальный клиент на Node.js
9. Проверка результата
10. Ограничения и совместимость
11. Официальные источники

Что такое Codex App Server

codex app-server запускает долгоживущий процесс, который предоставляет клиенту возможности агентного контура Codex. Он управляет потоками диалогов, конфигурацией и аутентификацией, передаёт события работы агента и связывает клиент с инструментами Codex.

Протокол двунаправленный. Клиент отправляет запросы, а сервер возвращает ответы и поток уведомлений. Сервер также может сам инициировать запрос, например запросить подтверждение команды, и приостановить ход до ответа пользователя.

App Server появился как интерфейс между Codex и расширением для VS Code. В инженерной статье OpenAI App Server назван основным способом встраивания полного агентного контура Codex в сторонние продукты; протокол проектируется с обратной совместимостью для старых клиентов.

Клиент можно написать на любом языке, который умеет обмениваться JSON-строками; локальные интеграции обычно запускают бинарный файл App Server как дочерний процесс. OpenAI упоминает реализации на TypeScript, Python, Go, Swift и Kotlin.

Что выбрать: App Server, SDK, exec или MCP

Если продукт должен воспроизводить полноценный пользовательский цикл Codex, начните с App Server. Если задача завершается одним неинтерактивным запуском, обычно достаточно codex exec.

Запуск через stdio

Установите совместимую версию Codex CLI по официальной инструкции для вашей операционной системы, затем запустите App Server:

codex app-server

В инженерной статье OpenAI для локальных приложений, IDE и TUI описан JSON-RPC-подобный протокол поверх stdio. Каждая строка стандартного ввода или вывода содержит одно JSON-сообщение, то есть используется формат JSONL.

Локальные приложения и IDE обычно поставляют или загружают подходящий бинарный файл Codex, запускают его как долгоживущий дочерний процесс и держат открытыми каналы stdin/stdout. В статье OpenAI для VS Code и Desktop App описан подход с платформенным бинарным файлом, закреплённым на протестированной версии.

Сетевые и удалённые транспорты зависят от версии CLI. Перед их использованием проверьте справку установленной версии и не открывайте локальный агентный процесс в интернет без аутентификации, шифрования и сетевого ограничения доступа.

Формат протокола и генерация типов

App Server использует облегчённый вариант JSON-RPC: сохраняются запросы, ответы и уведомления, но поле "jsonrpc": "2.0" опускается. При работе через stdio сообщения разделяются переводом строки.

Запрос содержит method, params и id:

{ "method": "thread/start", "id": 10, "params": {} }

Ответ повторяет id и содержит result либо error:

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

Уведомление не содержит id:

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

Не переписывайте типы протокола вручную. Codex CLI умеет генерировать определения TypeScript и комплект JSON Schema:

codex app-server generate-ts
codex app-server generate-json-schema

Перегенерируйте артефакты после обновления CLI и запускайте проверку типов или контрактные тесты до выкладки клиента.

Потоки, ходы и элементы

Протокол строится вокруг трёх сущностей:

• поток (thread) — сохраняемый диалог пользователя с агентом;
• ход (turn) — одна единица работы агента, запущенная пользовательским вводом;
• элемент (item) — отдельное сообщение, выполнение инструмента, запрос подтверждения, дифф или другой ввод и вывод.

Типичный жизненный цикл выглядит так:

1. Клиент отправляет единственный запрос initialize с описанием клиента и ждёт успешный ответ.
2. После ответа клиент отправляет предусмотренное протоколом уведомление initialized.
3. Клиент создаёт или возобновляет поток.
4. Клиент запускает ход и передаёт пользовательский ввод.
5. Сервер присылает уведомления о потоке, ходе и элементах.
6. Для потоковых элементов между началом и завершением приходят дельты.
7. Если действие требует разрешения, сервер отправляет запрос клиенту и ждёт решения.
8. Финальное уведомление turn/completed завершает ход.

Основные методы и события

Точный набор методов зависит от установленной версии. Типичная поверхность App Server включает:

Ключевые события пользовательского интерфейса:

• thread/started сообщает о доступном потоке;
• turn/started и turn/completed ограничивают один ход;
• item/started создаёт элемент в интерфейсе;
• события item/*/delta передают потоковые части содержимого;
• item/completed содержит финальное состояние элемента.

Для итогового состояния сообщения или инструмента используйте item/completed, а не самостоятельно собранную последнюю дельту.

При временной ошибке транспорта не считайте неизвестный запрос автоматически выполненным или невыполненным. В выпуске Codex 0.153.0 улучшено восстановление TUI после разрыва внешнего соединения с App Server: черновики и история сохраняются, а запросы с неопределённым результатом приостанавливаются для проверки. Собственному клиенту полезно применять такую же осторожную модель восстановления.

Подтверждения и песочница (sandbox)

App Server может запросить решение пользователя перед выполнением команды, изменением файлов или другим чувствительным действием. Клиент должен связать запрос с соответствующими threadId, turnId и itemId, показать понятное описание действия и вернуть только поддерживаемое схемой решение.

Безопасная логика интерфейса:

1. Создайте элемент после item/started.
2. При запросе подтверждения покажите точную команду, изменение или запрашиваемое разрешение.
3. Не продолжайте действие до явного ответа пользователя.
4. После разрешения или отказа дождитесь финального item/completed.
5. Не считайте закрытие окна подтверждением.

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

В Codex CLI 0.149.0 и новее политика подтверждений untrusted больше не поддерживается. Для ограничительного режима официальный Help Center предлагает сочетание sandbox_mode = "read-only" и approval_policy = "on-request".

Минимальный клиент на Node.js

Упрощённый пример запускает App Server, ждёт ответ на initialize, завершает рукопожатие, создаёт поток и отправляет запрос. Модель намеренно не зашита: доступность моделей зависит от версии CLI, способа входа и настроек рабочей области.

import { spawn } from "node:child_process";
import readline from "node:readline";

const proc = spawn("codex", ["app-server"], {
  stdio: ["pipe", "pipe", "inherit"],
});

const rl = readline.createInterface({ input: proc.stdout });

function send(message: unknown) {
  proc.stdin.write(JSON.stringify(message) + "\n");
}

rl.on("line", (line) => {
  const msg = JSON.parse(line);

  if (msg.id === 0 && msg.result) {
    send({ method: "initialized", params: {} });
    send({ method: "thread/start", id: 1, params: {} });
    return;
  }

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

  if (msg.method === "item/agentMessage/delta") {
    process.stdout.write(msg.params?.delta ?? "");
  }

  if (msg.method === "turn/completed") {
    process.stdout.write("\nTurn completed.\n");
  }
});

send({
  method: "initialize",
  id: 0,
  params: {
    clientInfo: {
      name: "my_product",
      title: "My Product",
      version: "0.1.0",
    },
  },
});

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

GPT-5.4 не следует использовать как универсальный пример модели: с 31 августа 2026 года она недоступна в Codex при входе через ChatGPT. Получайте доступные варианты через model/list или не задавайте модель, чтобы применить разрешённую конфигурацию по умолчанию.

Полезные сценарии

Codex внутри собственного продукта

Задача: добавить в редактор, админку или IDE диалог с Codex, потоковую печать ответа, историю и кнопки подтверждения действий.

Условия: подходящий бинарный файл Codex, реализованный JSONL-клиент и интерфейс для серверных запросов.

Действия: приложение запускает codex app-server, проходит рукопожатие, создаёт поток, запускает ход и отображает жизненный цикл каждого элемента.

Наблюдаемый результат: пользователь видит дельты ответа во время работы, а клиент получает финальные item/completed и turn/completed.

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

Обновление CLI без скрытой поломки клиента

Задача: проверить совместимость интеграции перед переходом на новую версию Codex.

Действия: закрепите текущую версию, сгенерируйте типы или JSON Schema из новой версии и запустите контрактные тесты на инициализацию, создание потока, один ход и подтверждение.

Наблюдаемый результат: несовместимые поля и методы обнаруживаются до выкладки.

Ограничение: сгенерированная схема соответствует конкретному бинарному файлу. Храните версию сервера и схему рядом с кодом клиента.

Восстановление после разрыва соединения

Задача: сохранить пользовательский интерфейс и не повторить потенциально выполненное действие после обрыва транспорта.

Действия: храните идентификаторы потоков, восстанавливайте сохранённую историю и помечайте запросы с неизвестным результатом для отдельной проверки.

Наблюдаемый результат: черновик и история остаются доступны, а сомнительная команда не запускается повторно автоматически.

Ограничение: конкретный механизм повторного подключения зависит от транспорта и версии CLI.

Проверка результата

Минимальная проверка локальной интеграции:

1. Запустите codex app-server как дочерний процесс.
2. Отправьте initialize и дождитесь ответа с тем же id.
3. После ответа отправьте уведомление initialized.
4. Выполните thread/start и сохраните полученный thread.id.
5. Отправьте turn/start с простым текстовым запросом.
6. Убедитесь, что пришли события элементов и финальный turn/completed.
7. Завершите процесс и проверьте обработку неожиданного разрыва соединения.

Для полной контрактной проверки добавьте сценарий с запросом подтверждения, отказом пользователя и проверкой финального состояния элемента.

Ограничения и совместимость

• App Server требует больше клиентского кода, чем SDK или codex exec: нужно обрабатывать запросы, ответы, уведомления, дельты и серверные запросы.
• Точные методы, поля, решения подтверждений и сетевые транспорты зависят от версии. Источником контракта должна быть схема установленного CLI.
• В выпуске Codex 0.153.0 CLI получил команды для перечисления, установки и удаления плагинов из удалённых маркетплейсов; журнал изменений также содержит API App Server для согласования плагинов. Не закрепляйте непроверенный список plugin-методов вручную.
• В актуальном README указано специальное ограничение для внутренних рабочих потоков: thread/archive и thread/delete отклоняют попытку удалить живого внутреннего worker ошибкой JSON-RPC -32600. Завершением такого worker управляет его владелец; после освобождения сохранённый поток можно архивировать или удалить обычным способом.
• Доступ к моделям зависит от типа аккаунта и конфигурации. При входе через ChatGPT GPT-5.4 и GPT-5.4 mini выведены из Codex 31 августа 2026 года.
• Это руководство основано на официальных источниках и не заявляет локальный прогон каждого метода. Перед внедрением воспроизведите критичные сценарии на закреплённой версии бинарного файла.

Официальные источники

• Документация Codex App Server
• README App Server в репозитории openai/codex
• Выпуски Codex CLI
• Как OpenAI построила App Server
• Справка по использованию Codex с подпиской ChatGPT

Следующий шаг

Если нужен разовый запуск Codex из терминала или скрипта, продолжите с руководством codex exec — как выполнять конкретные задачи Codex из терминала и скриптов.

Связанные материалы

• Статья: Редакция pimenov.ai на Codex app-server: архитектура собственного агентного приложения
• Блог: OpenAI выложил Symphony — и теперь ваш трекер задач может стать оркестратором кодящих агентов
• База знаний: Codex App — единый справочник по среде от OpenAI

App Server подходит командам, которым нужен собственный интерфейс поверх полного агентного контура Codex. До фиксации протокола в продукте полезно отдельно проверить модель безопасности, обновление клиента и восстановление после разрывов соединения.

Если захотите обсудить, как это применить у себя или в команде — пишите в Telegram @pimenov