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.

Для сравнения app-server с другими способами автоматизации используйте руководство «Agents API или Codex». Выбор зависит от задачи приложения, управления средой и того, где должен выполняться агент.

Запуск через 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 из терминала и скриптов.

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

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