Сервер приложений Codex

Codex app-server — это интерфейс, который Codex использует для поддержки полнофункциональных клиентов (например, расширения Codex для VS Code). Используйте его для глубокой интеграции с собственным продуктом: аутентификации, истории диалогов, подтверждений и потоковой передачи событий агента. Реализация app-server имеет открытый исходный код и находится в репозитории Codex на GitHub (openai/codex/codex-rs/app-server). Полный список компонентов Codex с открытым исходным кодом приведён на странице Открытый исходный код.

Подключение терминального интерфейса CLI

Режим удалённого терминального интерфейса позволяет запустить app-server на одном компьютере и подключить терминальный интерфейс Codex CLI с другого. Запустите прослушиватель WebSocket:

codex app-server --listen ws://127.0.0.1:4500

Затем подключите терминальный интерфейс:

codex --remote ws://127.0.0.1:4500

Для нелокального подключения настройте аутентификацию WebSocket и разместите соединение за TLS. Сохраните bearer-токен в переменной окружения и передайте её имя, не указывая сам токен в командной строке:

export CODEX_REMOTE_TOKEN="$(cat "$HOME/.codex/app-server-token")"
codex --remote wss://remote-host:4500 \
  --remote-auth-token-env CODEX_REMOTE_TOKEN

Параметр --remote принимает конечные точки ws://, wss://, unix:// и unix://PATH. Используйте WebSocket без шифрования только для localhost или соединения, перенаправленного через порт SSH.

Подключение удалённого хоста Code Mode

По умолчанию app-server запускает локальный хост Code Mode. Чтобы вместо него использовать удалённый хост, передайте его защищённый URL WebSocket:

codex app-server --code-mode-host wss://code-mode.example.com/host

--code-mode-host управляет исходящим соединением app-server с хостом Code Mode. Он не изменяет --listen, который определяет способ подключения клиентов к app-server. Все потоки в одном процессе app-server используют выбранное соединение с хостом Code Mode совместно.

Используйте wss:// для удалённого хоста. Используйте ws:// только для localhost или соединения, перенаправленного через SSH. Команда app-server и транспорт WebSocket экспериментальны и не поддерживаются для производственных нагрузок.

Протокол

Подобно MCP, codex app-server поддерживает двунаправленную связь с помощью сообщений JSON-RPC 2.0 (заголовок "jsonrpc":"2.0" при передаче не используется).

Поддерживаемые транспорты:

• stdio (--listen stdio://, по умолчанию): JSON с разделением по строкам (JSONL).
• websocket (--listen ws://IP:PORT, экспериментальный и неподдерживаемый): одно сообщение JSON-RPC на текстовый кадр WebSocket.
• Сокет Unix (--listen unix:// или --listen unix://PATH): соединения WebSocket через стандартный управляющий сокет app-server в Codex или пользовательский путь к сокету Unix с использованием стандартного рукопожатия HTTP Upgrade.
• off (--listen off): не предоставлять локальный транспорт.

При запуске с --listen ws://IP:PORT тот же прослушиватель также обслуживает базовые HTTP-проверки работоспособности:

• GET /readyz возвращает 200 OK, когда прослушиватель начинает принимать новые соединения.
• GET /healthz возвращает 200 OK, если запрос не содержит заголовок Origin.
• Запросы с заголовком Origin отклоняются с кодом 403 Forbidden.

Транспорт WebSocket экспериментален и не поддерживается. Локальные прослушиватели, такие как ws://127.0.0.1:PORT, подходят для сценариев с localhost и перенаправлением портов SSH. В ходе развёртывания нелокальные прослушиватели WebSocket в настоящее время по умолчанию разрешают соединения без аутентификации, поэтому настройте аутентификацию WebSocket, прежде чем предоставлять к ним удалённый доступ.

Поддерживаемые флаги аутентификации WebSocket:

• --ws-auth capability-token --ws-token-file /absolute/path
• --ws-auth capability-token --ws-token-sha256 HEX
• --ws-auth signed-bearer-token --ws-shared-secret-file /absolute/path

Для подписанных bearer-токенов также можно задать --ws-issuer, --ws-audience и --ws-max-clock-skew-seconds. Клиенты передают учётные данные как Authorization: Bearer <token> во время рукопожатия WebSocket, а app-server проверяет аутентификацию до JSON-RPC initialize.

Предпочитайте --ws-token-file передаче необработанных bearer-токенов в командной строке. Используйте --ws-token-sha256, только если клиент хранит необработанный токен с высокой энтропией в отдельном локальном хранилище секретов; хеш служит лишь средством проверки, а клиентам всё равно нужен исходный токен.

В режиме WebSocket app-server использует очереди ограниченного размера. Когда входная очередь запросов заполнена, сервер отклоняет новые запросы с кодом ошибки JSON-RPC -32001 и сообщением "Server overloaded; retry later." Клиентам следует повторять попытки с экспоненциально увеличивающейся задержкой и джиттером.

Схема сообщений

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

{ "method": "thread/start", "id": 10, "params": { "model": "gpt-5.6-terra" } }

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

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

{ "id": 10, "error": { "code": 123, "message": "Something went wrong" } }

В уведомлениях отсутствует id и используются только method и params:

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

Из CLI можно сгенерировать схему TypeScript или пакет JSON Schema. Каждый результат соответствует конкретной запущенной версии Codex, поэтому сгенерированные артефакты в точности соответствуют этой версии:

codex app-server generate-ts --out ./schemas
codex app-server generate-json-schema --out ./schemas

Начало работы

1. Запустите сервер с codex app-server (транспорт stdio по умолчанию), codex app-server --listen ws://127.0.0.1:4500 (TCP WebSocket) или codex app-server --listen unix:// (сокет Unix по умолчанию).
2. Подключите клиент через выбранный транспорт, затем отправьте initialize, а после него — уведомление initialized.
3. Запустите поток и ход, затем продолжайте читать уведомления из активного транспортного потока.

Пример (Node.js / TypeScript):

const proc = spawn("codex", ["app-server"], {
  stdio: ["pipe", "pipe", "inherit"],
});
const rl = readline.createInterface({ input: proc.stdout });

const send = (message: unknown) => {
  proc.stdin.write(`${JSON.stringify(message)}\n`);
};

let threadId: string | null = null;

rl.on("line", (line) => {
  const msg = JSON.parse(line) as any;
  console.log("server:", msg);

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

send({
  method: "initialize",
  id: 0,
  params: {
    clientInfo: {
      name: "my_product",
      title: "My Product",
      version: "0.1.0",
    },
  },
});
send({ method: "initialized", params: {} });
send({ method: "thread/start", id: 1, params: { model: "gpt-5.6-terra" } });

Основные примитивы

• Поток: диалог между пользователем и агентом Codex. Потоки содержат ходы.
• Ход: один запрос пользователя и последующая работа агента. Ходы содержат элементы и передают добавочные обновления в потоковом режиме.
• Элемент: единица входных или выходных данных (сообщение пользователя, сообщение агента, выполнение команды, изменение файла, вызов инструмента и т. д.).

Используйте API потоков для создания, просмотра и архивирования диалогов. Управляйте диалогом с помощью API ходов и передавайте ход выполнения через уведомления о ходе.

Обзор жизненного цикла

• Однократная инициализация для каждого соединения: сразу после открытия транспортного соединения отправьте запрос initialize с метаданными клиента, а затем отправьте initialized. Сервер отклоняет любые запросы в этом соединении до завершения рукопожатия.
• Запуск (или возобновление) потока: вызовите thread/start для нового диалога, thread/resume для продолжения существующего или thread/fork для создания ответвления истории с новым идентификатором потока.
• Начало хода: вызовите turn/start с целевым threadId и пользовательским вводом. Необязательные поля переопределяют модель, индивидуальность, cwd, политику песочницы и другие параметры.
• Корректировка активного хода: вызовите turn/steer, чтобы добавить пользовательский ввод в выполняющийся сейчас ход без создания нового хода.
• Потоковая передача событий: после turn/start продолжайте читать уведомления из stdout: thread/archived, thread/unarchived, item/started, item/completed, item/agentMessage/delta, сведения о ходе работы инструментов и другие обновления.
• Завершение хода: когда модель завершает работу или после отмены через turn/interrupt, сервер отправляет turn/completed с итоговым состоянием.

Инициализация

Перед вызовом любого другого метода клиенты должны отправить один запрос initialize для каждого транспортного соединения, а затем подтвердить его уведомлением initialized. Запросы, отправленные до инициализации, получают ошибку Not initialized, а повторные вызовы initialize в том же соединении возвращают Already initialized.

Сервер возвращает строку агента пользователя, которую он будет передавать вышестоящим сервисам, а также значения platformFamily и platformOs, описывающие целевую среду выполнения. Задайте clientInfo, чтобы идентифицировать свою интеграцию.

initialize.params.capabilities также поддерживает следующие возможности клиента:

• optOutNotificationMethods — точные имена методов уведомлений, которые следует подавлять для этого соединения. Сопоставление выполняется точно (без подстановочных знаков и префиксов); неизвестные имена принимаются и игнорируются.
• requestAttestation — согласие на инициированный сервером запрос attestation/generate. Настольные хосты, предоставляющие вышестоящую аттестацию, отвечают непрозрачным значением { "token": "..." }.
• mcpServerOpenaiFormElicitation — разрешение нижестоящим серверам MCP отправлять расширенный вариант mcpServer/elicitation/request в формате OpenAI.

Важно: используйте clientInfo.name, чтобы идентифицировать свой клиент для OpenAI Compliance Logs Platform. Если вы разрабатываете новую интеграцию Codex для корпоративного использования, обратитесь в OpenAI, чтобы её добавили в список известных клиентов. Дополнительные сведения см. в справочнике по журналам Codex.

Пример (из расширения Codex для VS Code):

{
  "method": "initialize",
  "id": 0,
  "params": {
    "clientInfo": {
      "name": "codex_vscode",
      "title": "Codex VS Code Extension",
      "version": "0.1.0"
    }
  }
}

Пример с отказом от уведомлений:

{
  "method": "initialize",
  "id": 1,
  "params": {
    "clientInfo": {
      "name": "my_client",
      "title": "My Client",
      "version": "0.1.0"
    },
    "capabilities": {
      "experimentalApi": true,
      "optOutNotificationMethods": ["thread/started", "item/agentMessage/delta"]
    }
  }
}

Включение экспериментального API

Некоторые методы и поля app-server намеренно доступны только при наличии возможности experimentalApi.

• Не указывайте capabilities (или задайте для experimentalApi значение false), чтобы использовать стабильную поверхность API; сервер будет отклонять экспериментальные методы и поля.
• Задайте для capabilities.experimentalApi значение true, чтобы включить экспериментальные методы и поля.

{
  "method": "initialize",
  "id": 1,
  "params": {
    "clientInfo": {
      "name": "my_client",
      "title": "My Client",
      "version": "0.1.0"
    },
    "capabilities": {
      "experimentalApi": true
    }
  }
}

Если клиент отправляет экспериментальный метод или поле без предварительного согласия, app-server отклоняет его со следующим сообщением:

<descriptor> requires experimentalApi capability

Обзор API

• thread/start — создаёт новый поток, отправляет thread/started и автоматически подписывает вас на события ходов и элементов этого потока.
• thread/resume — повторно открывает существующий поток по идентификатору, чтобы последующие вызовы turn/start дополняли его.
• thread/fork — создаёт ответвление потока с новым идентификатором, копируя сохранённую историю. Передайте lastTurnId, чтобы скопировать историю до этого хода включительно и исключить последующие ходы, или ephemeral: true, чтобы создать ответвление в памяти. Отправляет thread/started для нового потока; возвращаемые потоки содержат forkedFromId, если оно доступно.
• thread/read — читает сохранённый поток по идентификатору без его возобновления; задайте includeTurns, чтобы вернуть полную историю ходов. Возвращаемые объекты thread содержат status среды выполнения.
• thread/list — постранично просматривает журналы сохранённых потоков; поддерживает пагинацию на основе курсора, а также modelProviders, sourceKinds, archived, isPinned, cwd, useStateDbOnly, searchTerm и экспериментальные фильтры parentThreadId или ancestorThreadId. Возвращаемые объекты thread содержат status среды выполнения.
• thread/turns/list — экспериментальный; постранично просматривает историю ходов сохранённого потока без его возобновления. itemsView определяет, будут ли элементы ходов опущены, представлены в сводном виде или загружены полностью.
• thread/items/list — экспериментальный; постранично просматривает сохранённые элементы потока с возможностью ограничения одним turnId. Активное хранилище потоков должно поддерживать пагинацию элементов.
• thread/loaded/list — перечисляет идентификаторы потоков, загруженных в память в данный момент.
• thread/name/set — задаёт или изменяет отображаемое пользователю имя загруженного потока или сохранённого журнала выполнения; отправляет thread/name/updated.
• thread/goal/set — задаёт цель потока; отправляет thread/goal/updated.
• thread/goal/get — читает текущую цель потока.
• thread/goal/clear — удаляет цель потока; отправляет thread/goal/cleared.
• thread/metadata/update — изменяет метаданные сохранённого потока в SQLite, включая сохранённые gitInfo и isPinned.
• thread/archive — перемещает файл журнала потока в каталог архива и пытается архивировать журналы порождённых дочерних потоков, которые ещё не архивированы; при успехе возвращает {} и отправляет thread/archived для каждого архивированного потока.
• thread/delete — безвозвратно удаляет сохранённый активный или архивный поток и все порождённые дочерние потоки; при успехе возвращает {} и отправляет thread/deleted для каждого удалённого потока.
• thread/unsubscribe — отменяет подписку этого соединения на события ходов и элементов потока. Если это был последний подписчик, сервер выгружает поток по истечении периода бездействия без подписчиков и отправляет thread/closed.
• thread/unarchive — восстанавливает архивный журнал выполнения потока в каталог активных сеансов; возвращает восстановленный thread и отправляет thread/unarchived.
• thread/status/changed — уведомление, отправляемое при изменении status среды выполнения загруженного потока.
• thread/compact/start — запускает сжатие истории диалога для потока; немедленно возвращает {}, а ход выполнения передаётся через уведомления turn/* и item/*.
• thread/shellCommand — выполняет инициированную пользователем команду оболочки для потока. Она выполняется вне песочницы с полным доступом и не наследует политику песочницы потока.
• thread/backgroundTerminals/clean — останавливает все работающие фоновые терминалы потока (экспериментальный; требует capabilities.experimentalApi).
• thread/backgroundTerminals/list — перечисляет работающие фоновые терминалы загруженного потока (экспериментальный; требует capabilities.experimentalApi).
• thread/backgroundTerminals/terminate — завершает один работающий фоновый терминал по processId app-server (экспериментальный; требует capabilities.experimentalApi).
• thread/rollback — устарел; удаляет последние N ходов из контекста в памяти и сохраняет маркер отката; возвращает обновлённый thread.
• turn/start — добавляет пользовательский ввод в поток и запускает генерацию Codex; отвечает исходным turn и передаёт события в потоковом режиме. Для collaborationMode значение settings.developer_instructions: null означает «использовать встроенные инструкции для выбранного режима».
• thread/inject_items — добавляет необработанные элементы Responses API в видимую модели историю загруженного потока без запуска пользовательского хода.
• turn/steer — добавляет пользовательский ввод в активный выполняющийся ход потока; возвращает принятый turnId.
• turn/interrupt — запрашивает отмену выполняющегося хода; при успехе возвращается {}, а ход завершается с status: "interrupted".
• review/start — запускает рецензента Codex для потока; отправляет элементы enteredReviewMode и exitedReviewMode.
• command/exec — выполняет одну команду в песочнице сервера без запуска потока или хода.
• command/exec/write — записывает байты stdin в работающий сеанс command/exec или закрывает stdin.
• command/exec/resize — изменяет размер работающего сеанса command/exec с PTY.
• command/exec/terminate — останавливает работающий сеанс command/exec.
• command/exec/outputDelta (уведомление) — отправляется для кодированных в base64 фрагментов stdout/stderr из потокового сеанса command/exec.
• process/spawn — запускает явный сеанс процесса вне песочницы Codex (экспериментальный; требует capabilities.experimentalApi).
• process/writeStdin — записывает байты stdin в работающий сеанс process/spawn или закрывает stdin (экспериментальный).
• process/resizePty — изменяет размер работающего сеанса процесса с PTY (экспериментальный).
• process/kill — завершает работающий сеанс процесса (экспериментальный).
• process/outputDelta и process/exited (уведомления) — отправляются для потокового вывода процесса и состояния завершения процесса (экспериментальные).
• model/list — перечисляет доступные модели (задайте includeHidden: true, чтобы включить записи с hidden: true), варианты интенсивности, необязательный upgrade и inputModalities.
• modelProvider/capabilities/read — читает границы возможностей поставщика для сочетаний модели и поставщика.
• experimentalFeature/list — перечисляет флаги функций с метаданными стадии жизненного цикла и пагинацией на основе курсора.
• experimentalFeature/enablement/set — изменяет параметры среды выполнения в памяти для поддерживаемых ключей функций, таких как apps и plugins.
• environment/info — экспериментальный; подключается к настроенной среде выполнения и возвращает её оболочку и рабочий каталог по умолчанию.
• permissionProfile/list — перечисляет бета-профили разрешений и сведения о том, допускают ли их действующие требования, с пагинацией на основе курсора.
• collaborationMode/list — перечисляет предустановки режима совместной работы (экспериментальный, без пагинации).
• skills/list — перечисляет навыки для одного или нескольких значений cwd (поддерживает forceReload и необязательный perCwdExtraUserRoots).
• skills/extraRoots/set — заменяет дополнительные корневые каталоги уровня процесса, используемые для обнаружения автономных навыков, не сохраняя их.
• skills/changed (уведомление) — отправляется при изменении отслеживаемых локальных файлов навыков.
• hooks/list — перечисляет обнаруженные обработчики жизненного цикла для одного или нескольких значений cwd.
• marketplace/add — добавляет удалённый каталог плагинов и сохраняет его в пользовательской конфигурации каталогов.
• marketplace/remove — удаляет настроенный каталог и корневой каталог установленных из него компонентов, если он существует.
• marketplace/upgrade — обновляет настроенный Git-каталог или все настроенные Git-каталоги, если имя каталога не указано.
• plugin/list — находится в разработке; перечисляет обнаруженные каталоги плагинов и состояние плагинов, включая метаданные политик установки и аутентификации, ошибки загрузки каталогов, идентификаторы рекомендуемых плагинов и метаданные локальных, Git-, реестровых или удалённых источников плагинов. Сводки могут содержать удалённый version, локальный localVersion, структурированные светлые и тёмные значки и installPolicySource, который для текущих удалённых строк может иметь значение null, WORKSPACE_SETTING или IMPLICIT_CANONICAL_APP. Пока не вызывайте этот метод из производственных клиентов.
• plugin/read — находится в разработке; читает один плагин по пути каталога либо по имени удалённого каталога и имени плагина, включая встроенные навыки, приложения, имена серверов MCP и удалённый shareUrl плагина, если он предоставлен удалённым каталогом. Пока не вызывайте этот метод из производственных клиентов.
• plugin/install — находится в разработке; устанавливает плагин из каталога по пути или имени удалённого каталога. Пока не вызывайте этот метод из производственных клиентов.
• plugin/uninstall — находится в разработке; удаляет установленный плагин. Пока не вызывайте этот метод из производственных клиентов.
• plugin/skill/read — по запросу читает Markdown удалённого навыка плагина по удалённому каталогу, идентификатору плагина и имени навыка.
• app/installed — читает состояние среды выполнения установленных приложений, включая действующие состояния включения и доступности для вызова каждого приложения.
• app/list — перечисляет доступные приложения (коннекторы) с пагинацией и метаданными доступности и включения.
• app/read — получает метаданные и необязательные, предназначенные только для отображения сводки инструментов для указанных идентификаторов приложений.
• skills/config/write — включает или отключает навыки по пути.
• mcpServer/oauth/login — запускает вход через OAuth для настроенного сервера MCP; возвращает URL авторизации и по завершении отправляет mcpServer/oauthLogin/completed.
• tool/requestUserInput — предлагает пользователю 1–3 коротких вопроса для вызова инструмента (экспериментальный); вопросы могут задавать isOther для варианта со свободным вводом.
• mcpServer/elicitation/request (запрос сервера) — запрашивает у клиента структурированный ввод формы или подтверждение перехода по URL, запрошенного сервером MCP.
• item/permissions/requestApproval (запрос сервера) — просит клиента предоставить подмножество разрешений сети или файловой системы, запрошенных встроенным инструментом request_permissions.
• config/mcpServer/reload — повторно загружает конфигурацию серверов MCP с диска и ставит в очередь обновление загруженных потоков.
• mcpServerStatus/list — перечисляет серверы MCP, инструменты, ресурсы и состояние аутентификации (пагинация с курсором и лимитом). Используйте detail: "full" для полных данных или detail: "toolsAndAuthOnly", чтобы исключить ресурсы.
• mcpServer/resource/read — читает один ресурс MCP через инициализированный сервер MCP.
• mcpServer/tool/call — вызывает инструмент на настроенном для потока сервере MCP.
• mcpServer/startupStatus/updated (уведомление) — отправляется при изменении состояния запуска настроенного сервера MCP для загруженного потока.
• windowsSandbox/setupStart — запускает настройку песочницы Windows для режима elevated или unelevated; быстро возвращает результат, а позднее отправляет windowsSandbox/setupCompleted.
• feedback/upload — отправляет отчёт обратной связи (классификацию, необязательные причину, журналы и идентификатор диалога, а также необязательные вложения extraLogFiles).
• config/read — получает действующую конфигурацию на диске после разрешения всех уровней конфигурации.
• externalAgentConfig/detect — обнаруживает артефакты внешних агентов, которые можно перенести с помощью includeHome и необязательного cwds; каждый обнаруженный элемент содержит cwd (null для домашнего каталога).
• externalAgentConfig/import — применяет выбранные элементы миграции внешних агентов, принимая явные migrationItems с cwd (null для домашнего каталога). Поддерживаемые типы элементов включают конфигурацию, навыки, AGENTS.md, плагины, конфигурацию серверов MCP, субагентов, обработчики, команды и сеансы; при непустом импорте по мере выполнения работы отправляются externalAgentConfig/import/progress и externalAgentConfig/import/completed. Импорт плагинов и сеансов может завершаться асинхронно.
• config/value/write — записывает один ключ и значение конфигурации в пользовательский config.toml на диске.
• config/batchWrite — атомарно применяет изменения конфигурации к пользовательскому config.toml на диске.
• configRequirements/read — получает требования из requirements.toml и/или MDM, включая точную управляемую конфигурацию, списки разрешений, закреплённые featureRequirements и требования к резидентности и сети (либо null, если требования не настроены).
• fs/readFile, fs/writeFile, fs/createDirectory, fs/getMetadata, fs/readDirectory, fs/remove, fs/copy, fs/watch, fs/unwatch и fs/changed (уведомление) — выполняют операции с абсолютными путями файловой системы через API файловой системы app-server v2.

Сводки плагинов содержат объединение source. Локальные плагины возвращают { "type": "local", "path": ... }, записи каталогов на основе Git возвращают { "type": "git", "url": ..., "path": ..., "refName": ..., "sha": ... }, записи реестра пакетов возвращают { "type": "npm", "package": ..., "version": ..., "registry": ... }, а записи удалённого каталога возвращают { "type": "remote" }. Для записей, доступных только в удалённом каталоге, PluginMarketplaceEntry.path может иметь значение null; при чтении или установке таких плагинов передавайте remoteMarketplaceName вместо marketplacePath.

Модели

Перечисление моделей (model/list)

Перед отображением элементов выбора модели или индивидуальности вызовите model/list, чтобы узнать доступные модели и их возможности.

{ "method": "model/list", "id": 6, "params": { "limit": 20, "includeHidden": false } }
{ "id": 6, "result": {
  "data": [{
    "id": "gpt-5.6-sol",
    "model": "gpt-5.6-sol",
    "displayName": "GPT-5.6-Sol",
    "hidden": false,
    "defaultReasoningEffort": "low",
    "supportedReasoningEfforts": [{
      "reasoningEffort": "low",
      "description": "Fast responses with lighter reasoning"
    }],
    "inputModalities": ["text", "image"],
    "supportsPersonality": true,
    "isDefault": true
  }],
  "nextCursor": null
} }

Каждая запись модели может содержать:

• supportedReasoningEfforts — поддерживаемые моделью варианты интенсивности.
• defaultReasoningEffort — рекомендуемая клиентам интенсивность по умолчанию.
• upgrade — необязательный идентификатор рекомендуемой модели для предложений миграции в клиентах.
• upgradeInfo — необязательные метаданные обновления для предложений миграции в клиентах.
• hidden — скрыта ли модель из стандартного списка выбора.
• inputModalities — поддерживаемые моделью типы входных данных (например, text, image).
• supportsPersonality — поддерживает ли модель инструкции, зависящие от индивидуальности, например /personality.
• isDefault — является ли модель рекомендуемой по умолчанию.

По умолчанию model/list возвращает только модели, видимые в средстве выбора. Задайте includeHidden: true, если нужен полный список и вы хотите фильтровать его на стороне клиента с помощью hidden.

Если inputModalities отсутствует (в старых каталогах моделей), для обратной совместимости считайте его равным ["text", "image"].

Перечисление экспериментальных функций (experimentalFeature/list)

Используйте эту конечную точку, чтобы получить флаги функций с метаданными и стадией жизненного цикла:

{ "method": "experimentalFeature/list", "id": 7, "params": { "limit": 20 } }
{ "id": 7, "result": {
  "data": [{
    "name": "unified_exec",
    "stage": "beta",
    "displayName": "Unified exec",
    "description": "Use the unified PTY-backed execution tool.",
    "announcement": "Beta rollout for improved command execution reliability.",
    "enabled": false,
    "defaultEnabled": false
  }],
  "nextCursor": null
} }

stage может иметь значение beta, underDevelopment, stable, deprecated или removed. Для флагов вне бета-стадии displayName, description и announcement могут иметь значение null.

Проверка среды выполнения (экспериментальная)

Используйте environment/info, чтобы проверить настроенную удалённую среду перед началом работы в ней. Для метода требуется capabilities.experimentalApi = true.

{ "method": "environment/info", "id": 8, "params": { "environmentId": "devbox" } }
{ "id": 8, "result": {
  "shell": { "name": "zsh", "path": "/bin/zsh" },
  "cwd": "file:///workspace/project"
} }

cwd может иметь значение null. Если оно присутствует, это канонический URI file:, использующий собственный синтаксис путей среды. Неизвестные идентификаторы среды, а также сбои соединения или протокола возвращают ошибки запроса.

Потоки

• thread/read читает сохранённый поток без подписки на него; задайте includeTurns, чтобы включить ходы.
• thread/turns/list — экспериментальный метод, постранично просматривающий историю ходов сохранённого потока без его возобновления. Используйте itemsView, чтобы определить, будут ли элементы ходов опущены, представлены в сводном виде или загружены полностью.
• thread/items/list — экспериментальный метод, постранично просматривающий сохранённые элементы потока с возможностью ограничения одним ходом.
• thread/list поддерживает пагинацию на основе курсора, а также фильтрацию по modelProviders, sourceKinds, archived, isPinned, cwd, useStateDbOnly, searchTerm и экспериментальным parentThreadId или ancestorThreadId.
• thread/loaded/list возвращает идентификаторы потоков, находящихся в памяти.
• thread/archive перемещает сохранённый журнал JSONL потока в каталог архива и пытается архивировать журналы порождённых дочерних потоков, которые ещё не архивированы.
• thread/delete безвозвратно удаляет сохранённый активный или архивный поток и его порождённые дочерние потоки.
• thread/metadata/update изменяет метаданные сохранённого потока, включая сохранённые gitInfo и isPinned.
• thread/unsubscribe отменяет подписку текущего соединения на загруженный поток и после периода бездействия может вызвать thread/closed.
• thread/unarchive восстанавливает архивный журнал выполнения потока в каталог активных сеансов.
• thread/compact/start запускает сжатие и немедленно возвращает {}.
• thread/rollback устарел. Он удаляет последние N ходов из контекста в памяти и записывает маркер отката в сохранённый журнал JSONL потока.
• thread/inject_items добавляет необработанные элементы Responses API в видимую модели историю загруженного потока без запуска пользовательского хода.

Запуск или возобновление потока

Создавайте новый поток, когда требуется новый диалог Codex.

{ "method": "thread/start", "id": 10, "params": {
  "model": "gpt-5.6-terra",
  "cwd": "/Users/me/project",
  "approvalPolicy": "never",
  "sandbox": "workspaceWrite",
  "personality": "friendly",
  "serviceName": "my_app_server_client"
} }
{ "id": 10, "result": {
  "thread": {
    "id": "thr_123",
    "sessionId": "thr_123",
    "preview": "",
    "ephemeral": false,
    "modelProvider": "openai",
    "createdAt": 1730910000
  }
} }
{ "method": "thread/started", "params": { "thread": { "id": "thr_123" } } }

serviceName является необязательным. Задайте его, если хотите, чтобы app-server помечал метрики уровня потока именем сервиса вашей интеграции.

thread/start, thread/resume и thread/fork возвращают instructionSources — массив путей к загруженным файлам инструкций. Каждый путь использует собственный абсолютный синтаксис исходной среды, в том числе для удалённых сред.

Экспериментальные клиенты могут задать для historyMode в thread/start значение "legacy" (по умолчанию) или "paginated". Создание потоков с пагинацией пока не поддерживается и возвращает ошибку JSON-RPC -32601. App-server может перечислять и читать сводки существующих записей с пагинацией, но чтение полной истории, пагинация ходов и возобновление завершаются отказом, пока не появится поддержка истории с пагинацией.

Бета-клиенты, включившие capabilities.experimentalApi, могут передавать именованный идентификатор профиля разрешений в permissions вместо устаревшего поля sandbox. Не отправляйте permissions и sandbox одновременно. Используйте permissionProfile/list с cwd проекта, чтобы получить доступные профили и сведения о том, допускается ли каждый из них управляемыми требованиями.

thread.sessionId идентифицирует корень текущего дерева активных сеансов. Корневые потоки используют собственный идентификатор потока как идентификатор сеанса; ответвлённые потоки сохраняют идентификатор сеанса исходного корня. Клиентам следует читать идентификатор сеанса из thread.sessionId, а не выводить его из идентификатора потока.

Чтобы продолжить сохранённый сеанс, вызовите thread/resume с ранее записанным thread.id. Форма ответа совпадает с thread/start. Можно также передать те же переопределения конфигурации, которые поддерживает thread/start, например personality:

{ "method": "thread/resume", "id": 11, "params": {
  "threadId": "thr_123",
  "personality": "friendly"
} }
{ "id": 11, "result": { "thread": { "id": "thr_123", "name": "Bug bash notes", "ephemeral": false } } }

Само по себе возобновление потока не обновляет thread.updatedAt (или время изменения файла журнала выполнения). Временная метка обновляется при запуске хода.

Если в конфигурации включённый сервер MCP помечен как required и его инициализация завершается сбоем, thread/start и thread/resume завершаются ошибкой, а не продолжают работу без него.

dynamicTools в thread/start — экспериментальное поле (требует capabilities.experimentalApi = true). Codex сохраняет эти динамические инструменты в метаданных журнала выполнения потока и восстанавливает их при thread/resume, если новые динамические инструменты не указаны.

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

Управление целью потока

Используйте thread/goal/set, thread/goal/get и thread/goal/clear для управления тем же сохранённым состоянием цели, которое представлено как /goal в TUI.

{ "method": "thread/goal/set", "id": 13, "params": {
  "threadId": "thr_123",
  "objective": "Finish the migration and keep tests green",
  "status": "active",
  "tokenBudget": 40000
} }
{ "id": 13, "result": { "goal": {
  "threadId": "thr_123",
  "objective": "Finish the migration and keep tests green",
  "status": "active",
  "tokenBudget": 40000,
  "tokensUsed": 0,
  "timeUsedSeconds": 0
} } }
{ "method": "thread/goal/updated", "params": {
  "threadId": "thr_123",
  "goal": {
    "threadId": "thr_123",
    "objective": "Finish the migration and keep tests green",
    "status": "active",
    "tokenBudget": 40000,
    "tokensUsed": 0,
    "timeUsedSeconds": 0
  }
} }

Описание цели не должно быть пустым и может содержать не более 4 000 символов. Передача новой цели заменяет текущую цель и сбрасывает учёт использования. Передача текущей незавершённой цели или отсутствие objective обновляет состояние или бюджет токенов, сохраняя историю использования.

Чтобы создать ответвление от сохранённого сеанса, вызовите thread/fork с thread.id. Будет создан новый идентификатор потока и отправлено уведомление thread/started для него. Передайте lastTurnId, чтобы скопировать историю до этого хода включительно и исключить последующие ходы:

{ "method": "thread/fork", "id": 12, "params": { "threadId": "thr_123", "lastTurnId": "turn_456" } }
{ "id": 12, "result": { "thread": { "id": "thr_456", "sessionId": "thr_123", "forkedFromId": "thr_123" } } }
{ "method": "thread/started", "params": { "thread": { "id": "thr_456" } } }

App-server отклоняет выполняющийся lastTurnId. Если поле не указано, когда исходный поток находится в середине хода, в ответвление записывается маркер прерывания вместо сохранения непомеченного частичного хода.

Передайте ephemeral: true, чтобы создать ответвление в памяти, не добавляя его в списки сохранённых потоков:

{
  "method": "thread/fork",
  "id": 13,
  "params": {
    "threadId": "thr_123",
    "ephemeral": true
  }
}
{
  "id": 13,
  "result": {
    "thread": {
      "id": "thr_789",
      "sessionId": "thr_789",
      "forkedFromId": "thr_123",
      "ephemeral": true
    }
  }
}

Для эфемерных ответвлений потоков с пагинацией также требуется excludeTurns: true. Это поле является экспериментальным и требует capabilities.experimentalApi = true.

Если для потока задан отображаемый пользователю заголовок, app-server заполняет thread.name в ответах thread/list, thread/read, thread/resume, thread/unarchive и thread/rollback. thread/start и thread/fork могут не содержать name (или возвращать null), пока заголовок не будет задан позднее.

Чтение сохранённого потока (без возобновления)

Используйте thread/read, если нужны данные сохранённого потока, но вы не хотите возобновлять его или подписываться на его события.

• includeTurns — при значении true ответ содержит ходы потока; при значении false или отсутствии поля возвращается только сводка потока.
• Возвращаемые объекты thread содержат status среды выполнения (notLoaded, idle, systemError или active с activeFlags).

{ "method": "thread/read", "id": 19, "params": { "threadId": "thr_123", "includeTurns": true } }
{ "id": 19, "result": { "thread": { "id": "thr_123", "name": "Bug bash notes", "ephemeral": false, "status": { "type": "notLoaded" }, "turns": [] } } }

В отличие от thread/resume, thread/read не загружает поток в память и не отправляет thread/started.

Перечисление ходов потока

thread/turns/list — экспериментальный метод. Используйте его для постраничного просмотра истории ходов сохранённого потока без его возобновления. По умолчанию результаты сортируются от новых к старым, чтобы клиенты могли получать более старые ходы с помощью nextCursor. Ответ также содержит backwardsCursor; передайте его как cursor вместе с sortDirection: "asc", чтобы получить ходы, более новые, чем первый элемент предыдущей страницы.

itemsView определяет объём данных элементов хода в ответе:

• notLoaded исключает элементы.
• summary возвращает сводные данные элементов и используется по умолчанию, если поле отсутствует.
• full возвращает полные данные элементов.

{ "method": "thread/turns/list", "id": 20, "params": {
  "threadId": "thr_123",
  "limit": 50,
  "sortDirection": "desc",
  "itemsView": "summary"
} }
{ "id": 20, "result": {
  "data": [],
  "nextCursor": "older-turns-cursor-or-null",
  "backwardsCursor": "newer-turns-cursor-or-null"
} }

thread/items/list также является экспериментальным. Он постранично просматривает сохранённые элементы без возобновления потока. Передайте turnId, чтобы ограничить результаты одним ходом, или не указывайте его, чтобы просматривать элементы всего потока. Активное хранилище потоков должно поддерживать пагинацию элементов; в противном случае сервер возвращает ошибку неподдерживаемого метода.

Перечисление потоков (с пагинацией и фильтрами)

thread/list позволяет отобразить интерфейс истории. По умолчанию результаты сортируются по createdAt от новых к старым. Фильтры применяются до пагинации. Передайте любое сочетание следующих параметров:

• cursor — непрозрачная строка из предыдущего ответа; не указывайте для первой страницы.
• limit — если значение не задано, сервер использует подходящий размер страницы по умолчанию.
• sortKey — created_at (по умолчанию), updated_at или recency_at.
• sortDirection — desc (по умолчанию) или asc.
• modelProviders — ограничивает результаты указанными поставщиками; отсутствие значения, null или пустой массив включает всех поставщиков.
• sourceKinds — ограничивает результаты указанными источниками потоков. Если параметр отсутствует или равен [], сервер по умолчанию включает только интерактивные источники: cli и vscode.
• archived — при значении true перечисляет только архивные потоки. При значении false или отсутствии параметра перечисляет неархивные потоки (по умолчанию).
• isPinned — если указан, возвращает только потоки с соответствующим сохранённым состоянием закрепления. Не указывайте его, чтобы вернуть как закреплённые, так и незакреплённые потоки.
• cwd — ограничивает результаты потоками, текущий рабочий каталог сеанса которых в точности совпадает с этим путём или одним из путей в массиве. Относительные пути разрешаются от рабочего каталога процесса app-server.
• useStateDbOnly — при значении true возвращает результаты базы данных состояний без сканирования журналов потоков JSONL для восстановления метаданных. Не указывайте его или передайте false для стандартного поведения со сканированием и восстановлением.
• searchTerm — ограничивает результаты потоками, извлечённый заголовок которых содержит этот фрагмент текста с учётом регистра.
• parentThreadId — ограничивает результаты непосредственными дочерними потоками указанного родительского потока. Этот фильтр является экспериментальным и требует capabilities.experimentalApi = true.
• ancestorThreadId — ограничивает результаты порождёнными потомками указанного потока на любой глубине. Этот фильтр является экспериментальным и требует capabilities.experimentalApi = true; не сочетайте его с parentThreadId.

sourceKinds принимает следующие значения:

• cli
• vscode
• exec
• appServer
• subAgent
• subAgentReview
• subAgentCompact
• subAgentThreadSpawn
• subAgentOther
• unknown

Пример:

{ "method": "thread/list", "id": 20, "params": {
  "cursor": null,
  "limit": 25,
  "sortKey": "created_at"
} }
{ "id": 20, "result": {
  "data": [
    { "id": "thr_a", "preview": "Create a TUI", "ephemeral": false, "isPinned": true, "modelProvider": "openai", "createdAt": 1730831111, "updatedAt": 1730831111, "name": "TUI prototype", "status": { "type": "notLoaded" } },
    { "id": "thr_b", "preview": "Fix tests", "ephemeral": false, "isPinned": false, "modelProvider": "openai", "createdAt": 1730750000, "updatedAt": 1730750000, "status": { "type": "notLoaded" } }
  ],
  "nextCursor": "opaque-token-or-null"
} }

Если nextCursor равен null, достигнута последняя страница.

Обновление метаданных сохранённого потока

Используйте thread/metadata/update, чтобы изменить метаданные сохранённого потока без его возобновления. Задайте isPinned, чтобы закрепить или открепить поток, либо измените gitInfo, чтобы обновить сохранённые метаданные Git. Неуказанные поля остаются без изменений; явный null удаляет сохранённое значение метаданных Git.

{ "method": "thread/metadata/update", "id": 21, "params": {
  "threadId": "thr_123",
  "isPinned": true,
  "gitInfo": { "branch": "feature/sidebar-pr" }
} }
{ "id": 21, "result": {
  "thread": {
    "id": "thr_123",
    "isPinned": true,
    "gitInfo": { "sha": null, "branch": "feature/sidebar-pr", "originUrl": null }
  }
} }

Отслеживание изменений состояния потока

thread/status/changed отправляется при каждом изменении состояния среды выполнения загруженного потока. Полезная нагрузка содержит threadId и новый status.

{
  "method": "thread/status/changed",
  "params": {
    "threadId": "thr_123",
    "status": { "type": "active", "activeFlags": ["waitingOnApproval"] }
  }
}

Перечисление загруженных потоков

thread/loaded/list возвращает идентификаторы потоков, загруженных в память в данный момент.

{ "method": "thread/loaded/list", "id": 21 }
{ "id": 21, "result": { "data": ["thr_123", "thr_456"] } }

Отмена подписки на загруженный поток

thread/unsubscribe удаляет подписку текущего соединения на поток. Ответ содержит одно из следующих состояний:

• unsubscribed, если соединение было подписано и теперь подписка удалена.
• notSubscribed, если соединение не было подписано на этот поток.
• notLoaded, если поток не загружен.

Если это был последний подписчик, сервер сохраняет поток загруженным, пока в течение 30 минут у него не будет ни подписчиков, ни активности. По истечении льготного периода app-server выгружает поток и отправляет переход thread/status/changed в notLoaded, а также thread/closed.

{ "method": "thread/unsubscribe", "id": 22, "params": { "threadId": "thr_123" } }
{ "id": 22, "result": { "status": "unsubscribed" } }

Если позднее срок действия потока истечёт:

{ "method": "thread/status/changed", "params": {
    "threadId": "thr_123",
    "status": { "type": "notLoaded" }
} }
{ "method": "thread/closed", "params": { "threadId": "thr_123" } }

Архивирование потока

Используйте thread/archive, чтобы переместить сохранённый журнал потока (хранящийся на диске в виде файла JSONL) в каталог архивных сеансов. При архивировании потока также предпринимается попытка архивировать порождённые дочерние потоки, которые ещё не архивированы.

{ "method": "thread/archive", "id": 22, "params": { "threadId": "thr_b" } }
{ "id": 22, "result": {} }
{ "method": "thread/archived", "params": { "threadId": "thr_b" } }
{ "method": "thread/archived", "params": { "threadId": "thr_child" } }

Архивированные потоки не будут отображаться в последующих вызовах thread/list, если не передать archived: true. Сервер отправляет одно уведомление thread/archived для каждого фактически архивированного потока; если созданный дочерний поток невозможно архивировать, запрос всё равно может завершиться успешно без уведомления об архивировании этого дочернего потока.

Удаление потока

Используйте thread/delete, чтобы безвозвратно удалить сохранённый активный или архивированный поток и созданные им дочерние потоки. Перед возвратом успешного результата сервер удаляет существующие файлы развёртывания и связанные метаданные; отсутствующие файлы развёртывания считаются уже удалёнными. Временные корневые потоки удалить нельзя.

{ "method": "thread/delete", "id": 23, "params": { "threadId": "thr_b" } }
{ "id": 23, "result": {} }
{ "method": "thread/deleted", "params": { "threadId": "thr_b" } }
{ "method": "thread/deleted", "params": { "threadId": "thr_child" } }

Восстановление потока из архива

Используйте thread/unarchive, чтобы переместить развёртывание архивированного потока обратно в каталог активных сеансов.

{ "method": "thread/unarchive", "id": 24, "params": { "threadId": "thr_b" } }
{ "id": 24, "result": { "thread": { "id": "thr_b", "name": "Bug bash notes" } } }
{ "method": "thread/unarchived", "params": { "threadId": "thr_b" } }

Запуск сжатия потока

Используйте thread/compact/start, чтобы вручную запустить сжатие истории потока. Запрос немедленно возвращает {}.

App-server передаёт ход выполнения в виде стандартных уведомлений turn/* и item/* в том же threadId, включая жизненный цикл элемента contextCompaction (сначала item/started, затем item/completed).

{ "method": "thread/compact/start", "id": 25, "params": { "threadId": "thr_b" } }
{ "id": 25, "result": {} }

Выполнение команды оболочки в потоке

Используйте thread/shellCommand для инициированных пользователем команд оболочки, относящихся к потоку. Запрос немедленно возвращает {}, а ход выполнения передаётся через стандартные уведомления turn/* и item/*.

Этот API работает вне песочницы с полным доступом и не наследует политику песочницы потока. Клиенты должны предоставлять к нему доступ только для команд, явно инициированных пользователем.

Если в потоке уже есть активный ход, команда выполняется как вспомогательное действие этого хода, а её форматированный вывод добавляется в поток сообщений хода. Если поток бездействует, app-server запускает для команды оболочки отдельный ход.

{ "method": "thread/shellCommand", "id": 26, "params": { "threadId": "thr_b", "command": "git status --short" } }
{ "id": 26, "result": {} }

Очистка фоновых терминалов

Используйте thread/backgroundTerminals/clean, чтобы остановить все работающие фоновые терминалы, связанные с потоком. Этот метод экспериментальный и требует capabilities.experimentalApi = true.

{ "method": "thread/backgroundTerminals/clean", "id": 27, "params": { "threadId": "thr_b" } }
{ "id": 27, "result": {} }

Используйте thread/backgroundTerminals/list, чтобы просмотреть работающие фоновые терминалы загруженного потока. Запрос поддерживает стандартную пагинацию cursor и limit, а возвращаемый processId представляет собой идентификатор процесса app-server. Этот метод экспериментальный и требует capabilities.experimentalApi = true:

{ "method": "thread/backgroundTerminals/list", "id": 28, "params": { "threadId": "thr_b" } }
{ "id": 28, "result": { "data": [
  {
    "itemId": "item_456",
    "processId": "42",
    "command": "python3 -m http.server",
    "cwd": "/workspace",
    "osPid": null,
    "cpuPercent": null,
    "rssKb": null
  }
], "nextCursor": null } }

Используйте thread/backgroundTerminals/terminate с этим processId, чтобы остановить один фоновый терминал. Этот метод экспериментальный и требует capabilities.experimentalApi = true:

{ "method": "thread/backgroundTerminals/terminate", "id": 29, "params": { "threadId": "thr_b", "processId": "42" } }
{ "id": 29, "result": { "terminated": true } }

Откат последних ходов

thread/rollback устарел и будет удалён. Он удаляет последние записи numTurns из контекста в памяти и сохраняет маркер отката в журнале развёртывания. Возвращаемый thread содержит turns, заполненный после отката.

{ "method": "thread/rollback", "id": 30, "params": { "threadId": "thr_b", "numTurns": 1 } }
{ "id": 30, "result": { "thread": { "id": "thr_b", "name": "Bug bash notes", "ephemeral": false } } }

Ходы

Поле input принимает список элементов:

• { "type": "text", "text": "Explain this diff" }
• { "type": "image", "url": "https://.../design.png" }
• { "type": "localImage", "path": "/tmp/screenshot.png" }

Для каждого хода можно переопределить параметры конфигурации (модель, уровень усилий, личность, cwd, политику песочницы, сводку). Если они указаны, эти параметры становятся значениями по умолчанию для последующих ходов в том же потоке. outputSchema применяется только к текущему ходу. Для sandboxPolicy.type = "externalSandbox" задайте networkAccess равным restricted или enabled; для workspaceWrite значение networkAccess остаётся логическим.

Для turn/start.collaborationMode значение settings.developer_instructions: null означает «использовать встроенные инструкции для выбранного режима», а не очистить инструкции режима.

Доступ на чтение в песочнице (ReadOnlyAccess)

sandboxPolicy поддерживает явное управление доступом на чтение:

• readOnly: необязательный access (по умолчанию { "type": "fullAccess" } либо ограниченные корневые каталоги).
• workspaceWrite: необязательный readOnlyAccess (по умолчанию { "type": "fullAccess" } либо ограниченные корневые каталоги).

Структура ограниченного доступа на чтение:

{
  "type": "restricted",
  "includePlatformDefaults": true,
  "readableRoots": ["/Users/me/shared-read-only"]
}

В macOS includePlatformDefaults: true добавляет специально подобранную стандартную политику платформы Seatbelt для сеансов с ограниченным чтением. Это повышает совместимость инструментов, не предоставляя при этом широкого доступа ко всему /System.

Примеры:

{ "type": "readOnly", "access": { "type": "fullAccess" } }

{
  "type": "workspaceWrite",
  "writableRoots": ["/Users/me/project"],
  "readOnlyAccess": {
    "type": "restricted",
    "includePlatformDefaults": true,
    "readableRoots": ["/Users/me/shared-read-only"]
  },
  "networkAccess": false
}

Запуск хода

{ "method": "turn/start", "id": 30, "params": {
  "threadId": "thr_123",
  "input": [ { "type": "text", "text": "Run tests" } ],
  "cwd": "/Users/me/project",
  "approvalPolicy": "unlessTrusted",
  "sandboxPolicy": {
    "type": "workspaceWrite",
    "writableRoots": ["/Users/me/project"],
    "networkAccess": true
  },
  "model": "gpt-5.6-terra",
  "effort": "medium",
  "summary": "concise",
  "personality": "friendly",
  "outputSchema": {
    "type": "object",
    "properties": { "answer": { "type": "string" } },
    "required": ["answer"],
    "additionalProperties": false
  }
} }
{ "id": 30, "result": { "turn": { "id": "turn_456", "status": "inProgress", "items": [], "error": null } } }

Добавление элементов в поток

Используйте thread/inject_items, чтобы добавить готовые элементы Responses API в историю запросов загруженного потока, не начиная пользовательский ход. Эти элементы сохраняются в развёртывании и включаются в последующие запросы к модели.

{ "method": "thread/inject_items", "id": 31, "params": {
  "threadId": "thr_123",
  "items": [
    {
      "type": "message",
      "role": "assistant",
      "content": [{ "type": "output_text", "text": "Previously computed context." }]
    }
  ]
} }
{ "id": 31, "result": {} }

Корректировка активного хода

Используйте turn/steer, чтобы добавить пользовательский ввод в активный выполняющийся ход.

• Укажите expectedTurnId; он должен совпадать с идентификатором активного хода.
• Если в потоке нет активного хода, запрос завершается ошибкой.
• turn/steer не отправляет новое уведомление turn/started.
• turn/steer не принимает переопределения на уровне хода (model, cwd, sandboxPolicy или outputSchema).

{ "method": "turn/steer", "id": 32, "params": {
  "threadId": "thr_123",
  "input": [ { "type": "text", "text": "Actually focus on failing tests first." } ],
  "expectedTurnId": "turn_456"
} }
{ "id": 32, "result": { "turnId": "turn_456" } }

Запуск хода (вызов навыка)

Явно вызовите навык, включив $<skill-name> в текстовый ввод и добавив рядом с ним элемент ввода skill.

{ "method": "turn/start", "id": 33, "params": {
  "threadId": "thr_123",
  "input": [
    { "type": "text", "text": "$skill-creator Add a new skill for triaging flaky CI and include step-by-step usage." },
    { "type": "skill", "name": "skill-creator", "path": "/Users/me/.codex/skills/skill-creator/SKILL.md" }
  ]
} }
{ "id": 33, "result": { "turn": { "id": "turn_457", "status": "inProgress", "items": [], "error": null } } }

Прерывание хода

{ "method": "turn/interrupt", "id": 31, "params": { "threadId": "thr_123", "turnId": "turn_456" } }
{ "id": 31, "result": {} }

При успешном выполнении ход завершается со значением status: "interrupted".

Проверка

review/start запускает проверяющий модуль Codex для потока и передаёт элементы проверки в потоковом режиме. Возможные цели:

• uncommittedChanges
• baseBranch (различия относительно ветки)
• commit (проверка конкретного коммита)
• custom (инструкции в свободной форме)

Используйте delivery: "inline" (по умолчанию), чтобы запустить проверку в существующем потоке, или delivery: "detached", чтобы создать ответвлённый поток проверки.

Пример запроса и ответа:

{ "method": "review/start", "id": 40, "params": {
  "threadId": "thr_123",
  "delivery": "inline",
  "target": { "type": "commit", "sha": "1234567deadbeef", "title": "Polish tui colors" }
} }
{ "id": 40, "result": {
  "turn": {
    "id": "turn_900",
    "status": "inProgress",
    "items": [
      { "type": "userMessage", "id": "turn_900", "content": [ { "type": "text", "text": "Review commit 1234567: Polish tui colors" } ] }
    ],
    "error": null
  },
  "reviewThreadId": "thr_123"
} }

Для отделённой проверки используйте "delivery": "detached". Ответ имеет ту же структуру, но reviewThreadId будет идентификатором нового потока проверки (отличным от исходного threadId). Перед потоковой передачей хода проверки сервер также отправляет уведомление thread/started для этого нового потока.

Codex передаёт обычное уведомление turn/started, а затем item/started с элементом enteredReviewMode:

{
  "method": "item/started",
  "params": {
    "item": {
      "type": "enteredReviewMode",
      "id": "turn_900",
      "review": "current changes"
    }
  }
}

По завершении работы проверяющего модуля сервер отправляет item/started и item/completed, содержащий элемент exitedReviewMode с итоговым текстом проверки:

{
  "method": "item/completed",
  "params": {
    "item": {
      "type": "exitedReviewMode",
      "id": "turn_900",
      "review": "Looks solid overall..."
    }
  }
}

Используйте это уведомление для отображения результатов проверяющего модуля в клиенте.

Выполнение процессов

process/* — экспериментальный API для явного управления процессами. Он требует capabilities.experimentalApi = true и работает вне песочницы Codex. Используйте его, только если ваш клиент намеренно предоставляет локальное управление процессами без песочницы.

Запустите процесс с помощью process/spawn и укажите processHandle, а затем используйте этот дескриптор для запросов ввода, изменения размера и завершения. Вывод передаётся через уведомления process/outputDelta, а завершение — через process/exited.

{ "method": "process/spawn", "id": 48, "params": {
  "command": ["python3", "-m", "pytest", "-q"],
  "processHandle": "pytest-1",
  "cwd": "/Users/me/project",
  "tty": true
} }
{ "id": 48, "result": {} }
{ "method": "process/outputDelta", "params": {
  "processHandle": "pytest-1",
  "stream": "stdout",
  "deltaBase64": "Li4u"
} }
{ "method": "process/exited", "params": {
  "processHandle": "pytest-1",
  "exitCode": 0
} }

Используйте process/writeStdin с deltaBase64, closeStdin или обоими, чтобы отправить ввод. Используйте process/resizePty для событий изменения размера PTY и process/kill, чтобы завершить работающий процесс.

Выполнение команд

command/exec выполняет одну команду (массив argv) в песочнице сервера без создания потока.

{ "method": "command/exec", "id": 50, "params": {
  "command": ["ls", "-la"],
  "cwd": "/Users/me/project",
  "sandboxPolicy": { "type": "workspaceWrite" },
  "timeoutMs": 10000
} }
{ "id": 50, "result": { "exitCode": 0, "stdout": "...", "stderr": "" } }

Используйте sandboxPolicy.type = "externalSandbox", если процесс сервера уже выполняется в песочнице и вы хотите, чтобы Codex пропустил собственное применение ограничений песочницы. Для режима внешней песочницы задайте networkAccess равным restricted (по умолчанию) или enabled. Для readOnly и workspaceWrite используйте ту же необязательную структуру access / readOnlyAccess, которая показана выше.

Примечания:

• Сервер отклоняет пустые массивы command.
• sandboxPolicy принимает ту же структуру, что и turn/start (например, dangerFullAccess, readOnly, workspaceWrite, externalSandbox).
• Если timeoutMs не указан, используется значение сервера по умолчанию.
• Задайте tty: true для сеансов на базе PTY и используйте processId, если планируете затем вызвать command/exec/write, command/exec/resize или command/exec/terminate.
• Задайте streamStdoutStderr: true, чтобы получать уведомления command/exec/outputDelta во время выполнения команды.

Чтение административных требований (configRequirements/read)

Используйте configRequirements/read, чтобы просмотреть действующие административные требования, загруженные из requirements.toml и/или MDM.

{ "method": "configRequirements/read", "id": 52, "params": {} }
{ "id": 52, "result": {
  "requirements": {
    "allowedApprovalPolicies": ["onRequest", "unlessTrusted"],
    "allowedSandboxModes": ["readOnly", "workspaceWrite"],
    "featureRequirements": {
      "personality": true,
      "unified_exec": false
    },
    "network": {
      "enabled": true,
      "allowedDomains": ["api.openai.com"],
      "allowUnixSockets": ["/tmp/example.sock"],
      "dangerouslyAllowAllUnixSockets": false
    }
  }
} }

result.requirements имеет значение null, если требования не настроены. Подробные сведения о поддерживаемых ключах и значениях см. в документации по requirements.toml.

Настройка песочницы Windows (windowsSandbox/setupStart)

Пользовательские клиенты Windows могут запускать настройку песочницы асинхронно, не блокируя проверку при запуске.

{ "method": "windowsSandbox/setupStart", "id": 53, "params": { "mode": "elevated" } }
{ "id": 53, "result": { "started": true } }

App-server запускает настройку в фоновом режиме, а затем отправляет уведомление о завершении:

{
  "method": "windowsSandbox/setupCompleted",
  "params": { "mode": "elevated", "success": true, "error": null }
}

Режимы:

• elevated — запуск настройки песочницы Windows с повышенными правами.
• unelevated — запуск устаревшей процедуры настройки/предварительной проверки.

Файловая система

API файловой системы v2 работают с абсолютными путями. Используйте fs/watch, когда клиенту требуется сбросить состояние пользовательского интерфейса после изменения файла или каталога.

{ "method": "fs/watch", "id": 54, "params": {
  "watchId": "0195ec6b-1d6f-7c2e-8c7a-56f2c4a8b9d1",
  "path": "/Users/me/project/.git/HEAD"
} }
{ "id": 54, "result": { "path": "/Users/me/project/.git/HEAD" } }
{ "method": "fs/changed", "params": {
  "watchId": "0195ec6b-1d6f-7c2e-8c7a-56f2c4a8b9d1",
  "changedPaths": ["/Users/me/project/.git/HEAD"]
} }
{ "method": "fs/unwatch", "id": 55, "params": {
  "watchId": "0195ec6b-1d6f-7c2e-8c7a-56f2c4a8b9d1"
} }
{ "id": 55, "result": {} }

Наблюдение за файлом приводит к отправке fs/changed для пути этого файла, в том числе при изменениях, выполненных посредством замены или переименования.

События

Уведомления о событиях — это инициируемый сервером поток данных о жизненных циклах потоков, ходов и содержащихся в них элементов. После запуска или возобновления потока продолжайте читать активный транспортный поток, чтобы получать уведомления thread/started, thread/archived, thread/unarchived, thread/closed, thread/status/changed, turn/*, item/* и serverRequest/resolved.

Отказ от уведомлений

Клиенты могут отключать отдельные уведомления для каждого соединения, передавая точные имена методов в initialize.params.capabilities.optOutNotificationMethods.

• Только точное совпадение: item/agentMessage/delta отключает только этот метод.
• Неизвестные имена методов игнорируются.
• Применяется к текущим уведомлениям thread/*, turn/*, item/* и связанным уведомлениям v2.
• Не применяется к запросам, ответам и ошибкам.

События нечёткого поиска файлов (экспериментальная функция)

API сеансов нечёткого поиска файлов отправляет уведомления для каждого запроса:

• fuzzyFileSearch/sessionUpdated — { sessionId, query, files } с текущими совпадениями для активного запроса.
• fuzzyFileSearch/sessionCompleted — { sessionId } после завершения индексирования и поиска совпадений для этого запроса.

События предупреждений

• configWarning — { summary, details?, path?, range? } для устранимых проблем конфигурации или инициализации.
• warning — { threadId?, message } для некритических предупреждений времени выполнения.

События настройки песочницы Windows

• windowsSandbox/setupCompleted — { mode, success, error }, отправляемый после завершения запроса windowsSandbox/setupStart.

События ходов

• turn/started — { turn } с идентификатором хода, пустым items и status: "inProgress".
• turn/completed — { turn }, где turn.status имеет значение completed, interrupted или failed; при сбоях передаётся { error: { message, codexErrorInfo?, additionalDetails? } }.
• turn/diff/updated — { threadId, turnId, diff } с последним агрегированным унифицированным списком различий по всем изменениям файлов в ходе.
• turn/plan/updated — { turnId, explanation?, plan } при каждой публикации или изменении плана агентом; каждая запись plan представляет собой { step, status } со значением status в pending, inProgress или completed.
• hook/started и hook/completed — { threadId, turnId?, run } при запуске перехватчика жизненного цикла и после появления итоговой сводки его выполнения.
• model/safetyBuffering/updated — { threadId, turnId, model, useCases, reasons, showBufferingUi, fasterModel }, когда ответ поступает во временный буфер безопасности.
• model/rerouted — { threadId, turnId, fromModel, toModel, reason }, когда сервис перенаправляет запрос другой модели.
• model/verification — { threadId, turnId, verifications }, когда сервис требует дополнительной проверки учётной записи.
• thread/tokenUsage/updated — обновления сведений об использовании для активного потока.

turn/diff/updated и turn/plan/updated сейчас содержат пустые массивы items, даже когда события элементов передаются в потоковом режиме. Используйте уведомления item/* как источник достоверных данных об элементах хода.

Элементы

ThreadItem — размеченное объединение, передаваемое в ответах ходов и уведомлениях item/*. Распространённые типы элементов:

• userMessage — {id, content}, где content представляет собой список пользовательских вводов (text, image или localImage).
• agentMessage — {id, text, phase?}, содержащий накопленный ответ агента. Если присутствует phase, в нём используются передаваемые по сети значения Responses API (commentary, final_answer).
• plan — {id, text}, содержащий текст предлагаемого плана в режиме планирования. Считайте итоговый элемент plan из item/completed авторитетным.
• reasoning — {id, summary, content}, где summary содержит потоковые сводки рассуждений, а content — необработанные блоки рассуждений.
• commandExecution — {id, command, cwd, status, commandActions, aggregatedOutput?, exitCode?, durationMs?}.
• fileChange — {id, changes, status} с описанием предлагаемых изменений; список changes содержит {path, kind, diff}.
• mcpToolCall — {id, server, tool, status, arguments, appContext?, pluginId?, result?, error?}. Для доверенных приложений MCP appContext может содержать connectorId, linkId, resourceUri, appName, templateId и стабильный коннектор actionName. В ранее сохранённых элементах новые метаданные могут отсутствовать. Используйте appContext.resourceUri вместо устаревшего mcpAppResourceUri верхнего уровня.
• dynamicToolCall — {id, tool, arguments, status, contentItems?, success?, durationMs?} для выполняемых клиентом динамических вызовов инструментов.
• collabToolCall — {id, tool, status, senderThreadId, receiverThreadId?, newThreadId?, prompt?, agentStatus?}.
• webSearch — {id, query, action?} для запросов веб-поиска, отправленных агентом.
• imageView — {id, path}, отправляемый при вызове агентом инструмента просмотра изображений.
• enteredReviewMode — {id, review}, отправляемый при запуске проверяющего модуля.
• exitedReviewMode — {id, review}, отправляемый по завершении работы проверяющего модуля.
• contextCompaction — {id}, отправляемый при сжатии истории беседы в Codex.

Для webSearch.action действие type может иметь значение search (query?, queries?), openPage (url?) или findInPage (url?, pattern?).

App-server объявляет устаревшим прежнее уведомление thread/compacted; используйте вместо него элемент contextCompaction.

Все элементы отправляют два общих события жизненного цикла:

• item/started — отправляет полный item в начале новой единицы работы; item.id совпадает с itemId, используемым в приращениях.
• item/completed — отправляет итоговый item после завершения работы; считайте его авторитетным состоянием.

Приращения элементов

• item/agentMessage/delta — добавляет потоковый текст сообщения агента.
• item/plan/delta — передаёт текст предлагаемого плана в потоковом режиме. Итоговый элемент plan может не полностью совпадать с объединёнными приращениями.
• item/reasoning/summaryTextDelta — передаёт удобочитаемые сводки рассуждений; summaryIndex увеличивается при открытии нового раздела сводки.
• item/reasoning/summaryPartAdded — обозначает границу между разделами сводки рассуждений.
• item/reasoning/textDelta — передаёт необработанный текст рассуждений в потоковом режиме (если модель это поддерживает).
• item/commandExecution/outputDelta — передаёт stdout/stderr команды; добавляйте приращения по порядку.
• item/fileChange/outputDelta — устаревшее уведомление совместимости для прежнего текстового вывода apply_patch. Текущие версии app-server его больше не отправляют; используйте элементы fileChange и turn/diff/updated.

Ошибки

При сбое хода сервер отправляет событие error с { error: { message, codexErrorInfo?, additionalDetails? } }, а затем завершает ход со значением status: "failed". Если доступен HTTP-статус вышестоящего сервиса, он указывается в codexErrorInfo.httpStatusCode.

Распространённые значения codexErrorInfo:

• ContextWindowExceeded
• UsageLimitExceeded
• HttpConnectionFailed (ошибки 4xx/5xx вышестоящего сервиса)
• ResponseStreamConnectionFailed
• ResponseStreamDisconnected
• ResponseTooManyFailedAttempts
• BadRequest, Unauthorized, SandboxError, InternalServerError, Other

Если HTTP-статус вышестоящего сервиса доступен, сервер передаёт его в httpStatusCode соответствующего варианта codexErrorInfo.

Подтверждения

В зависимости от настроек Codex пользователя для выполнения команд и изменения файлов может потребоваться подтверждение. App-server отправляет клиенту инициированный сервером запрос JSON-RPC, а клиент отвечает данными решения.

• Решения о выполнении команд: accept, acceptForSession, decline, cancel или { "acceptWithExecpolicyAmendment": { "execpolicy_amendment": ["cmd", "..."] } }.

• Решения об изменении файлов: accept, acceptForSession, decline, cancel.

• Запросы содержат threadId и turnId — используйте их, чтобы ограничить состояние пользовательского интерфейса активной беседой.

• Сервер возобновляет или отклоняет работу и завершает элемент со значением item/completed.

Подтверждения выполнения команд

Порядок сообщений:

1. item/started показывает ожидающий элемент commandExecution с command, cwd и другими полями.
2. item/commandExecution/requestApproval содержит itemId, threadId, turnId, необязательный reason, необязательный command, необязательный cwd, необязательный commandActions, необязательный proposedExecpolicyAmendment, необязательный networkApprovalContext и необязательный availableDecisions. При initialize.params.capabilities.experimentalApi = true данные также могут содержать экспериментальный additionalPermissions с описанием запрошенного для каждой команды доступа к песочнице. Все пути файловой системы внутри additionalPermissions передаются по сети в абсолютном виде.
3. Клиент отвечает одним из приведённых выше решений о подтверждении выполнения команды.
4. serverRequest/resolved подтверждает, что на ожидающий запрос получен ответ или он сброшен.
5. item/completed возвращает итоговый элемент commandExecution с status: completed | failed | declined.

Если присутствует networkApprovalContext, запрос относится к управляемому сетевому доступу (а не к общему подтверждению команды оболочки). Текущая схема v2 предоставляет целевые host и protocol; клиенты должны показывать запрос, предназначенный для сети, и не полагаться на то, что command будет понятным пользователю предварительным представлением команды оболочки.

Codex группирует одновременные запросы подтверждения сетевого доступа по назначению (host, протоколу и порту). Поэтому app-server может отправить один запрос, разрешающий несколько ожидающих обращений к одному назначению, тогда как разные порты одного хоста обрабатываются отдельно.

Подтверждения изменения файлов

Порядок сообщений:

1. item/started отправляет элемент fileChange с предлагаемыми changes и status: "inProgress".
2. item/fileChange/requestApproval содержит itemId, threadId, turnId, необязательный reason и необязательный grantRoot.
3. Клиент отвечает одним из приведённых выше решений о подтверждении изменения файла.
4. serverRequest/resolved подтверждает, что на ожидающий запрос получен ответ или он сброшен.
5. item/completed возвращает итоговый элемент fileChange с status: completed | failed | declined.

tool/requestUserInput

Когда клиент отвечает на item/tool/requestUserInput, app-server отправляет serverRequest/resolved с { threadId, requestId }. Если ожидающий запрос сбрасывается из-за запуска, завершения или прерывания хода до ответа клиента, сервер отправляет такое же уведомление об очистке.

Параметры запроса содержат autoResolutionMs в виде целочисленного тайм-аута в миллисекундах или null. При его наличии хост-клиенты могут автоматически разрешить запрос по истечении этого интервала, если пользователь не ответит.

Запросы разрешений

Встроенный инструмент request_permissions отправляет item/permissions/requestApproval с threadId, turnId, itemId, environmentId, cwd, необязательным reason и запрошенными сетевыми разрешениями или разрешениями файловой системы. Ответьте с помощью permissions, указав только предоставленное подмножество. Задайте scope равным "session", чтобы сохранить разрешение для последующих ходов в том же сеансе; не указывайте его или используйте "turn", чтобы предоставить разрешение на один ход. Разрешения, которые не были запрошены, игнорируются.

Запросы на предоставление данных от сервера MCP

Сервер MCP может прервать ход с помощью mcpServer/elicitation/request. Запрос содержит threadId, необязательный turnId, serverName и одну из следующих структур запроса:

• mode: "form" или mode: "openai/form" с message и requestedSchema.
• mode: "url" с message, url и elicitationId.

Ответьте с помощью action: "accept" и запрошенного content либо с помощью action: "decline" или "cancel" и content: null. Затем app-server отправит serverRequest/resolved. Чтобы получать вариант openai/form, подпишитесь на него с помощью initialize.params.capabilities.mcpServerOpenaiFormElicitation.

Динамические вызовы инструментов (экспериментальная функция)

dynamicTools в thread/start и соответствующая последовательность запросов или ответов item/tool/call — экспериментальные API.

Имена динамических инструментов и пространств имён должны соответствовать ограничениям именования Responses API. Не используйте зарезервированные имена пространств имён встроенных инструментов Codex.

При вызове динамического инструмента во время хода app-server отправляет:

1. item/started с item.type = "dynamicToolCall", status = "inProgress", а также tool и arguments.
2. item/tool/call в виде серверного запроса клиенту.
3. Ответ клиента с возвращёнными элементами содержимого.
4. item/completed с item.type = "dynamicToolCall", итоговым status и любым возвращённым значением contentItems или success.

Подтверждения вызовов инструментов MCP (приложения)

Вызовы инструментов приложений (коннекторов) также могут требовать подтверждения. Если вызов инструмента приложения имеет побочные эффекты, сервер может запросить подтверждение с помощью tool/requestUserInput и предложить варианты, такие как Принять, Отклонить и Отменить. Аннотации разрушительных операций всегда требуют подтверждения, даже если инструмент также объявляет менее привилегированные характеристики. Если пользователь отклоняет или отменяет запрос, связанный элемент mcpToolCall завершается с ошибкой без запуска инструмента.

Навыки

Вызовите навык, включив $<skill-name> в текстовый ввод. Добавьте элемент ввода skill (рекомендуется), чтобы сервер внедрил полные инструкции навыка и модели не пришлось самостоятельно разрешать его имя.

{
  "method": "turn/start",
  "id": 101,
  "params": {
    "threadId": "thread-1",
    "input": [
      {
        "type": "text",
        "text": "$skill-creator Add a new skill for triaging flaky CI."
      },
      {
        "type": "skill",
        "name": "skill-creator",
        "path": "/Users/me/.codex/skills/skill-creator/SKILL.md"
      }
    ]
  }
}

Если элемент skill не указан, модель всё равно проанализирует маркер $<skill-name> и попытается найти навык, что может увеличить задержку.

Пример:

$skill-creator Add a new skill for triaging flaky CI and include step-by-step usage.

Используйте skills/list, чтобы получить доступные навыки (при необходимости ограничив область с помощью cwds и forceReload). Можно также включить perCwdExtraUserRoots, чтобы сканировать дополнительные абсолютные пути как область user для определённых значений cwd. App-server игнорирует записи, чей cwd отсутствует в cwds. skills/list может повторно использовать кэшированный результат для каждого cwd; задайте forceReload: true, чтобы обновить данные с диска. При наличии сервер считывает interface и dependencies из SKILL.json.

{ "method": "skills/list", "id": 25, "params": {
  "cwds": ["/Users/me/project", "/Users/me/other-project"],
  "forceReload": true,
  "perCwdExtraUserRoots": [
    {
      "cwd": "/Users/me/project",
      "extraUserRoots": ["/Users/me/shared-skills"]
    }
  ]
} }
{ "id": 25, "result": {
  "data": [{
    "cwd": "/Users/me/project",
    "skills": [
      {
        "name": "skill-creator",
        "description": "Create or update a Codex skill",
        "enabled": true,
        "interface": {
          "displayName": "Skill Creator",
          "shortDescription": "Create or update a Codex skill"
        },
        "dependencies": {
          "tools": [
            {
              "type": "env_var",
              "value": "GITHUB_TOKEN",
              "description": "GitHub API token"
            },
            {
              "type": "mcp",
              "value": "github",
              "transport": "streamable_http",
              "url": "https://example.com/mcp"
            }
          ]
        }
      }
    ],
    "errors": []
  }]
} }

Сервер также отправляет уведомления skills/changed при изменении отслеживаемых локальных файлов навыков. Считайте это сигналом сброса данных и при необходимости повторно выполните skills/list с текущими параметрами.

Чтобы включить или отключить навык по пути:

{
  "method": "skills/config/write",
  "id": 26,
  "params": {
    "path": "/Users/me/.codex/skills/skill-creator/SKILL.md",
    "enabled": false
  }
}

Приложения (коннекторы)

Используйте app/installed, чтобы прочитать последний зафиксированный снимок среды выполнения установленных приложений. Каждый результат содержит id приложения, runtimeName (или null), фактическое состояние enabled и состояние callable. Приложение можно вызывать, только если фактическая конфигурация включает его и хотя бы один видимый модели инструмент соответствует политикам приложения и инструментов.

{
  "method": "app/installed",
  "id": 49,
  "params": {
    "threadId": "thread-1",
    "forceRefresh": false
  }
}
{
  "id": 49,
  "result": {
    "apps": [
      {
        "id": "demo-app",
        "runtimeName": "Demo App",
        "enabled": true,
        "callable": true
      }
    ]
  }
}

Не указывайте threadId, чтобы использовать глобальную конфигурацию вместо конфигурации загруженного потока. Задайте forceRefresh: true, чтобы обновить снимок среды выполнения коннекторов перед чтением. Если глобальная политика или политика рабочей области блокирует доступ приложений, обнаруженное приложение всё равно может отображаться со значениями enabled и callable, равными false.

Используйте app/list, чтобы получить доступные приложения. В CLI/TUI /apps — это средство выбора для пользователя; в пользовательских клиентах вызывайте app/list напрямую. Каждая запись содержит как isAccessible (доступно пользователю), так и isEnabled (включено в config.toml), чтобы клиенты могли отличать установку/доступ от локального включённого состояния. Записи приложений также могут содержать необязательные поля branding, appMetadata и labels.

{ "method": "app/list", "id": 50, "params": {
  "cursor": null,
  "limit": 50,
  "threadId": "thread-1",
  "forceRefetch": false
} }
{ "id": 50, "result": {
  "data": [
    {
      "id": "demo-app",
      "name": "Demo App",
      "description": "Example connector for documentation.",
      "logoUrl": "https://example.com/demo-app.png",
      "logoUrlDark": null,
      "distributionChannel": null,
      "branding": null,
      "appMetadata": null,
      "labels": null,
      "installUrl": "https://chatgpt.com/apps/demo-app/demo-app",
      "isAccessible": true,
      "isEnabled": true
    }
  ],
  "nextCursor": null
} }

Если указать threadId, управление доступностью функций приложений (features.apps) будет использовать снимок конфигурации этого потока. Если он не указан, app-server использует последнюю глобальную конфигурацию.

app/list возвращает результат после загрузки как доступных приложений, так и приложений из каталога. Задайте forceRefetch: true, чтобы обойти кэш приложений и получить свежие данные. Записи кэша заменяются только при успешном обновлении.

Сервер также отправляет уведомления app/list/updated при завершении загрузки любого источника (доступных приложений или приложений из каталога). Каждое уведомление содержит последний объединённый список приложений.

{
  "method": "app/list/updated",
  "params": {
    "data": [
      {
        "id": "demo-app",
        "name": "Demo App",
        "description": "Example connector for documentation.",
        "logoUrl": "https://example.com/demo-app.png",
        "logoUrlDark": null,
        "distributionChannel": null,
        "branding": null,
        "appMetadata": null,
        "labels": null,
        "installUrl": "https://chatgpt.com/apps/demo-app/demo-app",
        "isAccessible": true,
        "isEnabled": true
      }
    ]
  }
}

Используйте app/read, если идентификаторы приложений уже известны и нужны их метаданные, а не состояние установленной среды выполнения. Передавайте не более 100 appIds. Сервер сохраняет только первое вхождение каждого повторяющегося идентификатора и сохраняет этот порядок как в apps, так и в missingAppIds. Неизвестные или недоступные приложения возвращаются в missingAppIds без сбоя всего запроса.

{
  "method": "app/read",
  "id": 52,
  "params": {
    "appIds": ["demo-app", "missing-app"],
    "includeTools": true
  }
}
{
  "id": 52,
  "result": {
    "apps": [
      {
        "id": "demo-app",
        "name": "Demo App",
        "description": "Example connector for documentation.",
        "iconUrl": null,
        "iconUrlDark": null,
        "distributionChannel": null,
        "installUrl": null,
        "pluginDisplayNames": [],
        "toolSummaries": [
          {
            "name": "search",
            "title": "Search",
            "description": "Search the app.",
            "isEnabled": true,
            "disabledReason": null,
            "isReadOnly": true
          }
        ]
      }
    ],
    "missingAppIds": ["missing-app"]
  }
}

Задайте includeTools: true, чтобы запросить предназначенные только для отображения общедоступные сводки инструментов. Ответ с метаданными не содержит состояния установленной среды выполнения приложения и не разрешает вызов инструмента; используйте app/installed, чтобы проверить фактические состояния enabled и callable.

Вызовите приложение, вставив $<app-slug> в текстовый ввод и добавив элемент ввода mention с путём app://<id> (рекомендуется).

{
  "method": "turn/start",
  "id": 51,
  "params": {
    "threadId": "thread-1",
    "input": [
      {
        "type": "text",
        "text": "$demo-app Pull the latest updates from the team."
      },
      {
        "type": "mention",
        "name": "Demo App",
        "path": "app://demo-app"
      }
    ]
  }
}

Примеры RPC конфигурации для настроек приложений

Используйте config/read, config/value/write и config/batchWrite, чтобы просматривать или обновлять параметры управления приложениями в config.toml.

Чтение фактической структуры конфигурации приложений (включая _default и переопределения для отдельных инструментов):

{ "method": "config/read", "id": 60, "params": { "includeLayers": false } }
{ "id": 60, "result": {
  "config": {
    "apps": {
      "_default": {
        "enabled": true,
        "destructive_enabled": true,
        "open_world_enabled": true,
        "approvals_reviewer": "user",
        "default_tools_approval_mode": "auto"
      },
      "google_drive": {
        "enabled": true,
        "destructive_enabled": false,
        "approvals_reviewer": "auto_review",
        "default_tools_approval_mode": "prompt",
        "tools": {
          "files/delete": { "enabled": false, "approval_mode": "approve" }
        }
      }
    }
  }
} }

apps._default.approvals_reviewer задаёт проверяющий модуль для всех приложений, если он не переопределён значением конкретного приложения. Если оба значения отсутствуют, приложение наследует значение approvals_reviewer верхнего уровня. apps._default.default_tools_approval_mode задаёт резервный режим подтверждения для инструментов без переопределения на уровне приложения или инструмента. Управляемые требования к режиму подтверждения имеют приоритет над настройками режима подтверждения инструментов.

Обновление одной настройки приложения:

{
  "method": "config/value/write",
  "id": 61,
  "params": {
    "keyPath": "apps.google_drive.default_tools_approval_mode",
    "value": "prompt",
    "mergeStrategy": "replace"
  }
}

Атомарное применение нескольких изменений приложений:

{
  "method": "config/batchWrite",
  "id": 62,
  "params": {
    "edits": [
      {
        "keyPath": "apps._default.destructive_enabled",
        "value": false,
        "mergeStrategy": "upsert"
      },
      {
        "keyPath": "apps.google_drive.tools.files/delete.approval_mode",
        "value": "approve",
        "mergeStrategy": "upsert"
      }
    ]
  }
}

Обнаружение и импорт конфигурации внешнего агента

Используйте externalAgentConfig/detect, чтобы обнаружить артефакты внешнего агента, которые можно перенести, а затем передайте выбранные записи в externalAgentConfig/import.

Пример обнаружения:

{ "method": "externalAgentConfig/detect", "id": 63, "params": {
  "includeHome": true,
  "cwds": ["/Users/me/project"]
} }
{ "id": 63, "result": {
  "items": [
    {
      "itemType": "AGENTS_MD",
      "description": "Import /Users/me/project/CLAUDE.md to /Users/me/project/AGENTS.md.",
      "cwd": "/Users/me/project"
    },
    {
      "itemType": "SKILLS",
      "description": "Copy skill folders from /Users/me/.claude/skills to /Users/me/.agents/skills.",
      "cwd": null
    }
  ]
} }

Пример импорта:

{ "method": "externalAgentConfig/import", "id": 64, "params": {
  "migrationItems": [
    {
      "itemType": "AGENTS_MD",
      "description": "Import /Users/me/project/CLAUDE.md to /Users/me/project/AGENTS.md.",
      "cwd": "/Users/me/project"
    }
  ],
  "source": "claude-code"
} }
{ "id": 64, "result": { "importId": "8ae96ff3-3425-4f4c-8772-b6fd61502868" } }

Необязательный параметр импорта верхнего уровня source указывает продукт, который создал выбранные элементы миграции.

Сервер отправляет externalAgentConfig/import/progress по мере завершения обработки типов элементов, а externalAgentConfig/import/completed — после завершения всех синхронных и фоновых операций импорта. Эти уведомления содержат тот же importId из ответа и itemTypeResults с отдельными для каждого типа successes и failures. Завершение может наступить сразу после ответа или после выполнения фонового удалённого импорта.

{ "method": "externalAgentConfig/import/progress", "params": {
  "importId": "8ae96ff3-3425-4f4c-8772-b6fd61502868",
  "itemTypeResults": [
    {
      "itemType": "AGENTS_MD",
      "successes": [
        { "itemType": "AGENTS_MD", "cwd": "/Users/me/project", "source": null, "target": "/Users/me/project/AGENTS.md" }
      ],
      "failures": []
    }
  ]
} }
{ "method": "externalAgentConfig/import/completed", "params": {
  "importId": "8ae96ff3-3425-4f4c-8772-b6fd61502868",
  "itemTypeResults": [
    {
      "itemType": "AGENTS_MD",
      "successes": [
        { "itemType": "AGENTS_MD", "cwd": "/Users/me/project", "source": null, "target": "/Users/me/project/AGENTS.md" }
      ],
      "failures": []
    }
  ]
} }

Чтение ранее завершённых операций импорта:

{ "method": "externalAgentConfig/import/readHistories", "id": 65 }
{ "id": 65, "result": { "data": [
  {
    "importId": "8ae96ff3-3425-4f4c-8772-b6fd61502868",
    "completedAtMs": 1781784000000,
    "successes": [
      { "itemType": "AGENTS_MD", "cwd": "/Users/me/project", "source": null, "target": "/Users/me/project/AGENTS.md" }
    ],
    "failures": []
  }
] } }

Поддерживаемые значения itemType: AGENTS_MD, CONFIG, SKILLS, PLUGINS, MCP_SERVER_CONFIG, SUBAGENTS, HOOKS, COMMANDS и SESSIONS. Для элементов PLUGINS поле details.plugins перечисляет каждый marketplaceName и pluginNames, которые Codex может попытаться перенести. При обнаружении возвращаются только элементы, для которых ещё требуется работа. Например, Codex пропускает миграцию AGENTS, если AGENTS.md уже существует и не пуст, а импорт навыков не перезаписывает существующие каталоги навыков.

При обнаружении плагинов из .claude/settings.json Codex считывает настроенные источники маркетплейсов из extraKnownMarketplaces. Если enabledPlugins содержит плагины из claude-plugins-official, но источник маркетплейса отсутствует, Codex определяет anthropics/claude-plugins-official как источник.

Конечные точки аутентификации

Поверхность аутентификации и учётных записей JSON-RPC предоставляет методы запросов/ответов и инициируемые сервером уведомления (без id). Используйте их, чтобы определять состояние аутентификации, запускать или отменять вход, выходить из системы, просматривать ограничения частоты запросов ChatGPT и уведомлять владельцев рабочей области об исчерпании средств или достижении лимитов использования.

Режимы аутентификации

Codex поддерживает следующие режимы аутентификации. account/updated.authMode показывает активный режим и при наличии содержит текущий planType ChatGPT. account/read также сообщает сведения об учётной записи и плане.

• API key (apikey) — вызывающая сторона передаёт OpenAI API key с помощью type: "apiKey", а Codex сохраняет его для запросов API.
• Управляемый ChatGPT (chatgpt) — Codex управляет процессом OAuth ChatGPT, сохраняет токены и автоматически обновляет их. Начните с type: "chatgpt" для процесса в браузере или с type: "chatgptDeviceCode" для процесса с кодом устройства.
• Внешние токены ChatGPT (chatgptAuthTokens) — экспериментальный режим, предназначенный для хост-приложений, которые уже управляют жизненным циклом аутентификации пользователя в ChatGPT. Хост-приложение напрямую передаёт accessToken, chatgptAccountId и необязательный chatgptPlanType и должно обновлять токен по запросу.
• Amazon Bedrock — account/read представляет учётные записи Bedrock как type: "amazonBedrock" и указывает, получены ли учётные данные из управляемого Codex Bedrock API key (credentialSource: "codexManaged") или из внешней цепочки учётных данных AWS (credentialSource: "awsManaged"). account/updated.authMode использует bedrockApiKey для управляемых Codex Bedrock API key.

Обзор API

• account/read — получить текущие сведения об учётной записи; при необходимости обновить токены.
• account/login/start — начать вход (apiKey, chatgpt, chatgptDeviceCode или экспериментальный chatgptAuthTokens).
• account/login/completed (уведомление) — отправляется после завершения попытки входа (успешной или с ошибкой).
• account/login/cancel — отменить ожидающий управляемый вход в ChatGPT по loginId.
• account/logout — выйти из системы; вызывает account/updated.
• account/updated (уведомление) — отправляется при каждом изменении режима аутентификации (authMode: apikey, chatgpt, chatgptAuthTokens, agentIdentity, personalAccessToken, bedrockApiKey или null) и при наличии содержит planType.
• account/chatgptAuthTokens/refresh (запрос сервера) — запросить новые управляемые извне токены ChatGPT после ошибки авторизации.
• account/rateLimits/read — получить ограничения частоты запросов ChatGPT.
• account/rateLimits/updated (уведомление) — отправляется при каждом изменении ограничений частоты запросов ChatGPT пользователя.
• account/sendAddCreditsNudgeEmail — попросить ChatGPT отправить владельцу рабочей области электронное письмо об исчерпании средств или достижении лимита использования.
• account/rateLimitResetCredit/consume — использовать один заработанный сброс ограничения частоты запросов со значением idempotencyKey, предоставленным вызывающей стороной.
• account/usage/read — получить сводки активности токенов учётной записи ChatGPT и дневные интервалы.
• account/workspaceMessages/read — получить активные сообщения рабочей области, включая заголовки уведомлений при их наличии.
• mcpServer/oauthLogin/completed (уведомление) — отправляется после завершения процесса mcpServer/oauth/login; данные содержат { name, threadId, success, error? }. threadId может иметь значение null для процессов OAuth на уровне приложения или плагина.
• mcpServer/startupStatus/updated (уведомление) — отправляется при изменении состояния запуска настроенного сервера MCP; данные содержат { threadId, name, status, error, failureReason }. Для запуска на уровне приложения threadId имеет значение null. Если запуск завершился с ошибкой, failureReason: "reauthenticationRequired" означает, что сохранённые учётные данные OAuth истекли и их не удалось обновить, поэтому клиент должен предложить повторно подключить сервер.

1) Проверка состояния аутентификации

Запрос:

{ "method": "account/read", "id": 1, "params": { "refreshToken": false } }

Примеры ответов:

{ "id": 1, "result": { "account": null, "requiresOpenaiAuth": false } }

{ "id": 1, "result": { "account": null, "requiresOpenaiAuth": true } }

{
  "id": 1,
  "result": { "account": { "type": "apiKey" }, "requiresOpenaiAuth": true }
}

{
  "id": 1,
  "result": {
    "account": {
      "type": "amazonBedrock",
      "credentialSource": "codexManaged"
    },
    "requiresOpenaiAuth": false
  }
}

{
  "id": 1,
  "result": {
    "account": {
      "type": "amazonBedrock",
      "credentialSource": "awsManaged"
    },
    "requiresOpenaiAuth": false
  }
}

{
  "id": 1,
  "result": {
    "account": {
      "type": "chatgpt",
      "email": "user@example.com",
      "planType": "pro"
    },
    "requiresOpenaiAuth": true
  }
}

Примечания к полям:

• refreshToken (логическое значение): задайте true, чтобы принудительно обновить токен в управляемом режиме ChatGPT. В режиме внешних токенов (chatgptAuthTokens) app-server игнорирует этот флаг.
• email имеет значение null, если у учётной записи ChatGPT нет адреса электронной почты.
• requiresOpenaiAuth отражает активного поставщика; при значении false Codex может работать без учётных данных OpenAI.
• Amazon Bedrock сообщает credentialSource: "codexManaged", когда использует Bedrock API key под управлением Codex. Для внешнего пути учётных данных AWS сообщается credentialSource: "awsManaged". Это определяет выбранный источник учётных данных, но не подтверждает, что цепочка учётных данных AWS может разрешить учётные данные.

2) Вход с помощью API key

1. Отправьте:

   {
     "method": "account/login/start",
     "id": 2,
     "params": { "type": "apiKey", "apiKey": "sk-..." }
   }

2. Ожидайте:

   { "id": 2, "result": { "type": "apiKey" } }

3. Уведомления:

   {
     "method": "account/login/completed",
     "params": { "loginId": null, "success": true, "error": null }
   }

   {
     "method": "account/updated",
     "params": { "authMode": "apikey", "planType": null }
   }

3) Вход с помощью ChatGPT (процесс в браузере)

1. Начните:

   {
     "method": "account/login/start",
     "id": 3,
     "params": {
       "type": "chatgpt",
       "useHostedLoginSuccessPage": true,
       "appBrand": "chatgpt"
     }
   }

По умолчанию после успешного обратного вызова браузер перенаправляется на локальную страницу успешного входа. Задайте useHostedLoginSuccessPage: true, чтобы использовать размещённую страницу успешного входа, когда настройка организации не требуется. Если размещённая страница успешного входа включена, appBrand может иметь значение "codex" или "chatgpt"; пропущенные значения или null по умолчанию заменяются на "codex".

   {
     "id": 3,
     "result": {
       "type": "chatgpt",
       "loginId": "<uuid>",
       "authUrl": "https://chatgpt.com/...&redirect_uri=http%3A%2F%2Flocalhost%3A<port>%2Fauth%2Fcallback"
     }
   }

2. Откройте authUrl в браузере; app-server обслуживает локальный обратный вызов.
3. Дождитесь уведомлений:

   {
     "method": "account/login/completed",
     "params": { "loginId": "<uuid>", "success": true, "error": null }
   }

   {
     "method": "account/updated",
     "params": { "authMode": "chatgpt", "planType": "plus" }
   }

3b) Вход с помощью ChatGPT (процесс с кодом устройства)

Используйте этот процесс, когда клиент управляет процедурой входа или когда обратный вызов браузера работает ненадёжно.

1. Начните:

   {
     "method": "account/login/start",
     "id": 4,
     "params": { "type": "chatgptDeviceCode" }
   }

   {
     "id": 4,
     "result": {
       "type": "chatgptDeviceCode",
       "loginId": "<uuid>",
       "verificationUrl": "https://auth.openai.com/codex/device",
       "userCode": "ABCD-1234"
     }
   }

2. Покажите пользователю verificationUrl и userCode; за взаимодействие с пользователем отвечает интерфейс.
3. Дождитесь уведомлений:

   {
     "method": "account/login/completed",
     "params": { "loginId": "<uuid>", "success": true, "error": null }
   }

   {
     "method": "account/updated",
     "params": { "authMode": "chatgpt", "planType": "plus" }
   }

3c) Вход с помощью управляемых извне токенов ChatGPT (chatgptAuthTokens)

Используйте этот экспериментальный режим, только если хост-приложение управляет жизненным циклом аутентификации пользователя в ChatGPT и напрямую передаёт токены. Перед использованием этого типа входа клиенты должны задать capabilities.experimentalApi = true во время initialize.

1. Отправьте:

   {
     "method": "account/login/start",
     "id": 7,
     "params": {
       "type": "chatgptAuthTokens",
       "accessToken": "<jwt>",
       "chatgptAccountId": "org-123",
       "chatgptPlanType": "business"
     }
   }

2. Ожидайте:

   { "id": 7, "result": { "type": "chatgptAuthTokens" } }

3. Уведомления:

   {
     "method": "account/login/completed",
     "params": { "loginId": null, "success": true, "error": null }
   }

   {
     "method": "account/updated",
     "params": { "authMode": "chatgptAuthTokens", "planType": "business" }
   }

Когда сервер получает 401 Unauthorized, он может запросить у хост-приложения обновлённые токены:

{
  "method": "account/chatgptAuthTokens/refresh",
  "id": 8,
  "params": { "reason": "unauthorized", "previousAccountId": "org-123" }
}
{ "id": 8, "result": { "accessToken": "<jwt>", "chatgptAccountId": "org-123", "chatgptPlanType": "business" } }

После успешного ответа на обновление сервер повторяет исходный запрос. Время ожидания запросов истекает примерно через 10 секунд.

4) Отмена входа в ChatGPT

{ "method": "account/login/cancel", "id": 4, "params": { "loginId": "<uuid>" } }
{ "method": "account/login/completed", "params": { "loginId": "<uuid>", "success": false, "error": "..." } }

5) Выход из системы

{ "method": "account/logout", "id": 5 }
{ "id": 5, "result": {} }
{ "method": "account/updated", "params": { "authMode": null, "planType": null } }

6) Ограничения частоты запросов (ChatGPT)

{ "method": "account/rateLimits/read", "id": 6 }
{ "id": 6, "result": {
  "rateLimits": {
    "limitId": "codex",
    "limitName": null,
    "primary": { "usedPercent": 25, "windowDurationMins": 15, "resetsAt": 1730947200 },
    "secondary": null,
    "rateLimitReachedType": null
  },
  "rateLimitsByLimitId": {
    "codex": {
      "limitId": "codex",
      "limitName": null,
      "primary": { "usedPercent": 25, "windowDurationMins": 15, "resetsAt": 1730947200 },
      "secondary": null,
      "rateLimitReachedType": null
    },
    "codex_other": {
      "limitId": "codex_other",
      "limitName": "codex_other",
      "primary": { "usedPercent": 42, "windowDurationMins": 60, "resetsAt": 1730950800 },
      "secondary": null,
      "rateLimitReachedType": null
    }
  },
  "rateLimitResetCredits": {
    "availableCount": 2,
    "credits": [{
      "id": "RateLimitResetCredit_1",
      "resetType": "codexRateLimits",
      "status": "available",
      "grantedAt": 1781654400,
      "expiresAt": 1784246400,
      "title": "Rate-limit reset",
      "description": "Reset an eligible Codex rate-limit window."
    }]
  }
} }
{ "method": "account/rateLimits/updated", "params": {
  "rateLimits": {
    "limitId": "codex",
    "primary": { "usedPercent": 31, "windowDurationMins": 15, "resetsAt": 1730948100 }
  }
} }

Примечания к полям:

• rateLimits — обратно совместимое представление одного интервала.
• rateLimitsByLimitId (если присутствует) — представление нескольких интервалов с ключами по учитываемому limit_id (например, codex).
• limitId — идентификатор учитываемого интервала.
• limitName — необязательное понятное пользователю название интервала.
• usedPercent — текущее использование в пределах окна квоты.
• windowDurationMins — продолжительность окна квоты.
• resetsAt — временная метка Unix (в секундах) следующего сброса.
• planType включается, когда сервер возвращает план ChatGPT, связанный с интервалом.
• credits включается, когда сервер возвращает сведения об оставшихся средствах рабочей области.
• rateLimitReachedType определяет классифицированное сервером состояние лимита после его достижения.
• rateLimitResetCredits содержит доступное количество заработанных сбросов, если сервис его предоставляет; в противном случае имеет значение null.
• rateLimitResetCredits.credits имеет значение null, когда известно только количество. Пустой массив означает, что сервис получил подробные сведения и не обнаружил доступных средств. Сервис может ограничивать число строк с подробностями, поэтому availableCount является авторитетным значением.
• Каждая строка с подробностями содержит непрозрачный id, resetType, status, grantedAt, expiresAt (который может иметь значение null), title (который может иметь значение null) и description (который может иметь значение null).
• После использования сброса получите account/rateLimits/read.

7) Использование токенов (ChatGPT)

Используйте account/usage/read, чтобы получить поля сводки активности токенов ChatGPT и необязательные дневные интервалы.

{ "method": "account/usage/read", "id": 7 }
{ "id": 7, "result": {
  "summary": {
    "lifetimeTokens": 1234567,
    "peakDailyTokens": 45678,
    "longestRunningTurnSec": 540,
    "currentStreakDays": 8,
    "longestStreakDays": 14
  },
  "dailyUsageBuckets": [
    { "startDate": "2026-06-18", "tokens": 12345 }
  ]
} }

Примечания к полям:

• Значения summary могут быть равны null, если сервис ещё не вернул эту метрику.
• dailyUsageBuckets может иметь значение null; если поле присутствует, каждый интервал содержит startDate и tokens.
• Конечная точка требует аутентификации, поддерживаемой сервисами Codex. Подходят ChatGPT, внешние токены ChatGPT, удостоверение агента и аутентификация с помощью личного токена доступа; аутентификация только по API key и аутентификация Bedrock не подходят.

8) Заработанные сбросы ограничения частоты запросов (ChatGPT)

Используйте account/rateLimitResetCredit/consume, чтобы применить один заработанный сброс.

{ "method": "account/rateLimitResetCredit/consume", "id": 8, "params": { "idempotencyKey": "8ae96ff3-3425-4f4c-8772-b6fd61502868", "creditId": "RateLimitResetCredit_1" } }
{ "id": 8, "result": { "outcome": "reset" } }

Примечания к полям:

• idempotencyKey не должен быть пустым. Используйте UUID для каждой логической попытки погашения и повторно используйте то же значение при повторе этой попытки.
• creditId является необязательным. Если он указан, это должен быть непустой непрозрачный идентификатор из account/rateLimits/read. Если он не указан, сервис выбирает следующее доступное средство.
• reset означает, что средство было использовано.
• alreadyRedeemed означает, что то же погашение уже было завершено. Считайте это идемпотентным успехом и обновите ограничения учётной записи.
• nothingToReset означает, что нет подходящего окна ограничения частоты запросов для сброса.
• noCredit означает, что в учётной записи нет доступных заработанных средств сброса.
• После использования сброса получите account/rateLimits/read, а не пытайтесь вывести обновлённые окна из этого ответа.

9) Уведомление владельца рабочей области о лимите

Используйте account/sendAddCreditsNudgeEmail, чтобы попросить ChatGPT отправить владельцу рабочей области электронное письмо, когда средства исчерпаны или достигнут лимит использования.

{ "method": "account/sendAddCreditsNudgeEmail", "id": 9, "params": { "creditType": "credits" } }
{ "id": 9, "result": { "status": "sent" } }

Используйте creditType: "credits", когда средства рабочей области исчерпаны, или creditType: "usage_limit", когда достигнут лимит использования рабочей области. Если владелец уже был недавно уведомлён, статус ответа будет cooldown_active.

10) Сообщения рабочей области (ChatGPT)

Используйте account/workspaceMessages/read, чтобы получить активные сообщения текущей рабочей области, включая заголовки уведомлений при их наличии.

{ "method": "account/workspaceMessages/read", "id": 10 }
{ "id": 10, "result": { "featureEnabled": true, "messages": [
  { "messageId": "msg_123", "messageType": "headline", "messageBody": "Workspace maintenance starts at 5pm.", "createdAt": 1781395200, "archivedAt": null }
] } }