Codex «failed to start codex app-server» на Windows: причины и решения (2026)

«failed to start codex app-server» на Windows: диагностика за 30 секунд

Вы запустили Codex Desktop на Windows. Окно открывается или появляется иконка в трее, а затем вот это:

failed to start codex app-server: The system cannot find the path specified. (os error 3)

Локализованные сборки показывают то же самое на вашем языке. Немецкие пользователи видят Das System kann den angegebenen Pfad nicht finden. (os error 3). Код os error 3 неизменен: это Windows ERROR_PATH_NOT_FOUND.

Выполните эти три проверки по порядку. Первая, что вернёт неправильный результат, укажет на решение.

# 1. Which Codex packages are actually installed?
Get-AppxPackage *Codex* | Select-Object Name, Version, InstallLocation

# 2. Does your profile path contain non-ASCII characters?
echo $env:USERPROFILE

# 3. Is there more than one Codex version on PATH?
$env:PATH -split ';' | Select-String 'Codex'

Единственный факт, который экономит больше всего времени: Codex CLI и Codex Desktop являются разными программами. Если codex --version работает в обычном терминале, но приложение Desktop выдаёт ошибку app-server, то ваш аккаунт, ваш ключ и ваша установка Codex в порядке. Вы столкнулись с багом оболочки Desktop и можете продолжать выпускать код из CLI, пока его чинят. Этот запасной выход описан в последнем разделе статьи.

Каждое решение ниже привязано к реальному открытому тикету в трекере openai/codex по состоянию на 2026-07-16. Никаких выдуманных номеров версий.

Что на самом деле такое app-server (и почему возникает os error 3)

Codex Desktop представляет собой приложение Electron. Окно, которое вы видите, это тонкая оболочка интерфейса. Реальная работа происходит в отдельном дочернем процессе под названием app-server: общение с моделью, запуск Browser Use, выполнение задачи. Оболочка запускает app-server на старте и общается с ним через локальный сокет.

os error 3 возникает в тот момент, когда оболочка пытается запустить этот дочерний процесс, а Windows не может найти путь к исполняемому файлу, который ей велено запустить. Обратите внимание, чем это не является: это не сетевая ошибка, не ошибка авторизации, не превышение лимита. Сбой происходит ещё до того, как какой-либо запрос покидает вашу машину. У оболочки есть строка пути, эта строка не разрешается в файл, Windows возвращает ERROR_PATH_NOT_FOUND, и оболочка показывает это как failed to start codex app-server.

Codex Desktop (Electron UI shell)
        │
        │  spawn( <path-to-app-server> )   ← path resolved at install/launch
        ▼
   ┌─────────────────────────┐
   │  path is valid  ────────►│  app-server runs, chat + Browser Use work
   │                          │
   │  path is stale/wrong ───►│  os error 3  →  "failed to start codex app-server"
   └─────────────────────────┘

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

Когда чинить, а когда переходить на CLI

Прежде чем тратить час на приложение Desktop, решите, стоит ли оно того.

Чините приложение Desktop, когда

• Вам конкретно нужен Browser Use или другая внутренняя функция, которую предоставляет только приложение Desktop.
• Ваша команда стандартизировалась на приложении Desktop, и вам нужен паритет.
• Ошибка появилась после обновления, и вы подозреваете регрессию из-за устаревшего PATH (Решение 1 занимает две минуты на проверку).

Переходите на CLI, когда

• Вы в основном используете Codex для написания кода в терминале или редакторе. CLI делает всё то же, что app-server делает для этого сценария, и вообще не зависит от оболочки Electron.
• Ваше имя пользователя Windows содержит не-ASCII символы, а создание новой учётной записи мешает работе сильнее, чем просто использование CLI.
• Вы на заблокированной машине, где не можете менять права пакета из Store.

Правило остановки

Если вы выполнили Решения с 1 по 4, а app-server всё ещё не запускается, прекращайте отлаживать приложение. Установите CLI (npm i -g @openai/codex), убедитесь, что codex --version выводит версию, и работайте оттуда. Приложение Desktop не является обязательным условием для использования Codex. Гоняться за открытым багом Electron дальше четырёх решений значит впустую потратить целый день.

Кластер os error 3: открытые тикеты по состоянию на 2026-07-16

Вот карта того, о чём люди реально сообщают, чтобы вы могли сопоставить точный текст своей ошибки с первопричиной и решением. Каждый тикет ниже имеет статус OPEN.

Если текст вашей ошибки не совпадает точно ни с одним из этих, прочитайте ближайшее совпадение и возьмите его решение за отправную точку. Сама строка os error 3 соответствует #20206 и #20048; формулировка «Unable to locate the Codex CLI binary» соответствует #28392 и #28031; падение после запуска (code=1) с WARN о плагине соответствует #26440.

Решение 1: устаревший PATH указывает на старую версию пакета

Это самая частая причина и самая быстрая для проверки. Обновления Codex выходят как новые пакеты Windows Store с папкой, в имени которой зашита версия, например OpenAI.Codex_26.422.8496.0_x64__2p2nqsd0c76g0. Если в PATH всё ещё есть ссылка на старую версию пакета, оболочка может разрешить путь к app-server относительно папки, где больше нет нужного файла.

В #20206 автор отметил ровно это: после перезапуска PATH указывал только на текущую версию пакета, но до перезапуска в PATH была ещё и старая версия пакета. Убрать это и есть шаг первый.

# List every Codex package still installed
Get-AppxPackage *Codex* | Select-Object Name, Version, PackageFullName

# Look for stale WindowsApps entries on PATH
$env:PATH -split ';' | Select-String 'OpenAI.Codex'

Если вы видите две и более разных строки версии, удалите старые:

# Remove the Store package entirely, then reinstall a single clean copy
Get-AppxPackage OpenAI.Codex | Remove-AppxPackage

Переустановите из одного источника (из Store, а лучше через npm или официальный установщик, описанные в Решении 4). После переустановки откройте новый терминал (изменения PATH никогда не применяются к уже открытым оболочкам) и перезапустите Codex Desktop.

Один перезапуск здесь не решение. Он сбрасывает устаревший PATH в памяти, но если базовая причина неверного пути структурная (Решение 2, 3 или 4), ошибка сразу возвращается. #20206 служит доказательством: полный перезапуск Desktop его не устранил.

Решение 2: не-ASCII символы в пути профиля Windows

Codex пишет и читает состояние внутри каталога вашего профиля: C:\Users\<you>\.codex\.... Если <you> содержит не-ASCII символы (скандинавские буквы вроде å ö ø, немецкие умлауты, латиница с диакритикой или CJK), разрешение пути может сломаться так, что это проявится как os error 3. Это давний режим отказа для инструментария Windows, рассчитанного на ASCII-пути, и запуск app-server в Codex от него не застрахован.

Сначала проверьте:

echo $env:USERPROFILE
# C:\Users\Håkon\...   ← the å is the problem

Если ваш путь профиля состоит только из чистого ASCII, это не ваша причина; переходите к Решению 3. Если в нём есть не-ASCII символы, чище всего изолировать проблему через нового локального пользователя с именем только из ASCII:

Settings → Accounts → Other users → Add account
→ create a local account with an ASCII-only username (e.g. "dev")
→ sign in as that user
→ install and run Codex there

Если под ASCII-пользователем Codex Desktop запускается чисто, вы подтвердили причину. Дальше у вас два надёжных варианта: держать выделенный ASCII-профиль под Codex или отказаться от приложения Desktop и использовать CLI, который можно направить на любой рабочий каталог независимо от вашего имени пользователя. Переименование папки профиля существующего пользователя Windows рискованно и того не стоит; вместо этого создайте новую учётную запись.

Решение 3: песочница Microsoft Store блокирует встроенный codex.exe

Приложения, упакованные в Store, устанавливаются в C:\Program Files\WindowsApps\, каталог, доступный только для чтения и с ограниченным доступом для большинства процессов. В #28031 встроенный codex.exe есть внутри пакета, но не запускается, потому что ОС отказывает в доступе, и app-server так и не стартует. Автор пробовал сброс приложения, удаление и переустановку, очистку CODEX_CLI_PATH, но сбой сохранялся.

Проверьте, что у вас:

# Where did the package land, and is the binary there?
$pkg = (Get-AppxPackage *Codex*).InstallLocation
Get-ChildItem $pkg -Recurse -ErrorAction SilentlyContinue |
  Where-Object { $_.Name -match 'codex' } |
  Select-Object FullName, Length

Если бинарник присутствует внутри WindowsApps, но приложение всё равно падает с разновидностью ошибки «access denied», не боритесь с песочницей. Надёжный путь состоит в том, чтобы вовсе перестать полагаться на встроенный бинарник из Store:

# 1. Remove the Store package
Get-AppxPackage OpenAI.Codex | Remove-AppxPackage

# 2. Install the CLI outside the sandbox, into a normal user-writable location
npm i -g @openai/codex

# 3. Confirm it runs
codex --version

Теперь бинарник codex живёт внутри вашего глобального префикса npm (обычное, исполняемое расположение), а не внутри песочницы Store. Если вы всё ещё хотите приложение Desktop, направьте его на этот бинарник через CODEX_CLI_PATH (см. Решение 4). Если нет, просто используйте CLI.

Решение 4: «Unable to locate the Codex CLI binary» (бинарник отсутствует или не на месте)

Оболочка Electron ожидает найти Codex CLI по пути bin/codex внутри своих ресурсов или по пути из переменной окружения CODEX_CLI_PATH. Когда ни то, ни другое не выполнено, вы получаете явное сообщение из #28392 и #28031:

Codex failed to start.

Unable to locate the Codex CLI binary. Set CODEX_CLI_PATH or
ensure the Electron resources include bin/codex.

Связанные сообщения (#25671, #25886) показывают тот же класс сбоя с другими формулировками: «Codex app-server is not available», «Unable to find Electron app at …» или сокет, закрывающийся с code=4294967295. Все это случаи, когда оболочка не может добраться до рабочего бинарника app-server.

Решение состоит в том, чтобы дать оболочке бинарник, который она сможет найти. Установите CLI из источника, который попадает в обычное, исполняемое расположение:

# Option A: npm (recommended; needs Node 16+ on PATH)
npm i -g @openai/codex
where.exe codex          # note the resolved path, e.g. C:\Users\you\AppData\Roaming\npm\codex

# Option B: winget
winget upgrade OpenAI.Codex
# or, if not yet installed:
winget install OpenAI.Codex

Затем направьте Codex Desktop на этот бинарник, задав CODEX_CLI_PATH равным разрешённому пути:

# Use the path where.exe printed above
[Environment]::SetEnvironmentVariable(
  "CODEX_CLI_PATH",
  "$env:APPDATA\npm\codex.cmd",
  "User"
)

Закройте все терминалы и перезапустите приложение, чтобы оно подхватило новую переменную уровня User. Если после установки CODEX_CLI_PATH app-server всё равно не поднимается (с чем столкнулись несколько авторов), значит у приложения на вашей машине более глубокий баг разрешения, и вашим ответом станет прямой путь через CLI из раздела «Обходной путь».

Решение 5: кешированный манифест плагина роняет app-server

Другая форма сбоя: приложение всё же запускается, а затем app-server завершается через несколько секунд. В #26440 app-server падает с code=1 при загрузке кешированного манифеста плагина. Логи показывают WARN о том, что interface.defaultPrompt[0] плагина превышает лимит Codex в 128 символов (проблемный кешированный манифест содержал строку примерно из 313 символов), после чего app-server завершается неожиданно. Это происходит и в Codex Desktop, и в Codex в VS Code, и может сработать даже когда чат простаивает. Плагин, на который наткнулся автор, вообще не был включён в config.toml.

Если ваша ошибка представляет собой падение после запуска с code=1, а не чистый os error 3 на старте, очистите кеш плагинов:

# Back up, then remove the cached plugin tree under your profile
Move-Item "$env:USERPROFILE\.codex\.tmp\plugins" `
          "$env:USERPROFILE\.codex\.tmp\plugins.bak" -ErrorAction SilentlyContinue

Перезапустите Codex. Он пересоздаст кеш плагинов с нуля. Если манифест конкретного плагина как раз выводит за лимит в 128 символов, то держать этот плагин вне конфига не даст кешу снова его включить. Это отдельная первопричина от ошибок пути выше. Не применяйте Решения с 1 по 4 к падению плагина с code=1; они его не затронут.

Типичные шаблоны сбоев в Codex Desktop под Windows

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

Два вывода из этого шаблона. Во-первых, «app-server не запускается» это не один баг. Это как минимум четыре бага (путь, песочница, отсутствие бинарника, сбой плагина), и у каждого свой тикет. Во-вторых, пакет из Store перепредставлен по всему кластеру. Если вы установились из Microsoft Store и застряли, переход на CLI из npm или официального установщика убирает целую категорию этих проблем разом.

Читайте логи, прежде чем что-либо менять

Диалог ошибки даёт вам одну строку. Логи дают путь, который Codex реально пытался запустить, и это как раз та деталь, что говорит, какая из причин выше у вас. Две минуты здесь избавляют от прогона решений для неправильной первопричины.

Codex пишет состояние и логи внутри вашего профиля. Начните оттуда:

# Inspect the Codex state directory
Get-ChildItem "$env:USERPROFILE\.codex" -Recurse -ErrorAction SilentlyContinue |
  Select-Object FullName, Length, LastWriteTime |
  Sort-Object LastWriteTime -Descending |
  Select-Object -First 20

Смотрите сначала на самые недавно записанные файлы; сбой, который вы только что вызвали, будет вверху. Когда лог называет конкретный путь в сообщении os error 3, сравните его с тем, что реально установлено:

# What path does the app think the app-server lives at, vs. what is on disk?
Get-AppxPackage *Codex* | Select-Object Name, Version, InstallLocation
Test-Path "C:\Program Files\WindowsApps\OpenAI.Codex_*\app\resources\codex.exe"

Если Test-Path возвращает False, значит бинарника, который ищет оболочка, действительно нет (Решение 4). Если возвращает True, но приложение всё равно падает с разновидностью «access denied», файл есть, а песочница блокирует запуск (Решение 3). Если всплывают две версии пакета, у вас случай устаревшего PATH (Решение 1). Одна эта проверка различает три из пяти причин.

Для случая падения после запуска полезным сигналом служит строка в логе CLI, а не диалог. В #26440 лог напечатал точный путь к манифесту плагина и причину (prompt must be at most 128 characters) прямо перед выходом с code=1. Прогрепайте каталог состояния на этот WARN:

# Find the plugin manifest that is crashing the app-server
Select-String -Path "$env:USERPROFILE\.codex\*.log" -Pattern "defaultPrompt|exited unexpectedly|os error 3" -ErrorAction SilentlyContinue

Практическое правило: os error 3 на старте означает проблему пути, выход с code=1 через секунды после отрисовки окна означает проблему плагина/манифеста, а сообщение о закрытии websocket означает app-server, умирающий раньше, чем он успевает передать управление интерфейсу. Сопоставьте строку лога с таблицей кластера, затем запускайте только решение для этой первопричины.

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

 app-server error
        │
        ├─ "os error 3" at startup ──────────┐
        │                                     │
        │   two package versions on PATH? ──► Fix 1 (remove stale version)
        │   non-ASCII in $env:USERPROFILE? ─► Fix 2 (ASCII profile)
        │
        ├─ "Unable to locate the CLI binary"
        │        │
        │        ├─ binary present but blocked ► Fix 3 (Store sandbox)
        │        └─ binary absent ────────────► Fix 4 (install + CODEX_CLI_PATH)
        │
        ├─ "code=1" + defaultPrompt WARN ────► Fix 5 (clear plugin cache)
        │
        └─ none apply, `codex --version` works ► Fallback (use the CLI)

Единственная ветка, которая завершает любой путь: если codex --version работает в терминале, у вас есть рабочий Codex независимо от состояния приложения Desktop. Именно поэтому обходной путь не является утешительным призом; он часто быстрее любого из пяти решений.

Codex в VS Code показывает ту же ошибку

Расширение Codex для VS Code запускает тот же app-server, что и приложение Desktop, поэтому там всплывают идентичные сбои. Падение плагина из #26440 воспроизводится и там. Если расширение выдаёт ошибку app-server, а ваш терминальный codex здоров, решение то же: расширение натыкается на баг класса Desktop, и запуск codex напрямую во встроенном терминале его обходит. Не переустанавливайте расширение в ожидании другого результата; код app-server общий.

Когда приложение Desktop не запускается: продолжайте работать из CLI

Если вы прошли решения, а приложение Desktop всё ещё отказывается запускаться, остановитесь. Оно вам не нужно. Codex CLI представляет собой самостоятельную программу, которая не зависит ни от оболочки Electron, ни от её app-server, и работает на нативном Windows.

Бесплатно / индивидуально: запускайте CLI напрямую

Установите один раз, запускайте в любом терминале:

# Needs Node 16+ on PATH
npm i -g @openai/codex
codex --version
codex

Если codex --version печатает версию, а codex открывает интерактивную сессию, у вас есть полная функциональность Codex для работы с кодом: без app-server, без Electron, без всех режимов отказа Windows Desktop выше. Это ответ для ситуации из #20048 в точности: рабочий npm CLI, пока приложение Desktop выдаёт os error 3. Используйте CLI, заведите/отслеживайте баг Desktop и двигайтесь дальше.

Платно / команда: закрепите одну чистую установку и обойдите Store

Команды раз за разом страдают от пакета из Store, потому что каждая машина натыкается на песочницу и проблемы устаревших версий независимо. Стандартизируйтесь на npm CLI с закреплённой версией, чтобы каждый разработчик и CI-раннер были идентичны:

# On every dev machine and CI runner
npm i -g @openai/codex
codex --version   # confirm the same version everywhere

Закрепление версии убирает разброс «работает на моей машине», который создаёт помашинная упаковка Store. Если кому-то всё ещё нужен интерфейс Desktop, он может направить его на этот CLI через CODEX_CLI_PATH (Решение 4), а не полагаться на встроенный бинарник.

Любой тариф: направьте CLI через OpenAI-совместимого провайдера

Если вы открываете Codex ради работы над кодом, и вам всё равно, идёт ли запрос напрямую в OpenAI, вы можете направить Codex CLI на OpenAI-совместимый эндпоинт через шлюз. Это полностью развязывает «могу ли я запустить Codex» и «здорово ли приложение Desktop»: CLI общается со шлюзом, шлюз общается с той моделью, которую вы настроили.

Ofox предоставляет единый базовый URL https://api.ofox.ai/v1, который принимает Codex CLI. Когда приложение Desktop лежит на Windows, вы настраиваете CLI один раз и продолжаете выпускать код против выбранной модели.

# ~/.codex/config.toml  (on Windows: C:\Users\<you>\.codex\config.toml)
model_provider = "ofox-codex"

[model_providers.ofox-codex]
name = "Ofox"
base_url = "https://api.ofox.ai/v1"
env_key = "OFOX_API_KEY"
wire_api = "responses"

Codex требует wire_api = "responses". Актуальный Codex убрал старое значение wire_api = "chat"; его передача приводит к сбою на этапе загрузки конфига ещё до отправки любого запроса. Шлюз, реализующий только /v1/chat/completions, работать не будет, поэтому убедитесь, что ваш шлюз документирует поддержку Responses API, и протестируйте с реальным ключом, прежде чем на него полагаться.

Две сопутствующие статьи разбирают смежные проблемы CLI напрямую. Если сам CLI не разрешается в вашем PATH, начните с решений для codex: command not found. Если CLI работает, но приложение Desktop прячет пользовательские модели, смотрите Codex Desktop не показывает пользовательские модели.

Как следить за статусом бага app-server

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

Следите за точным тикетом, совпадающим с вашей строкой ошибки, а не за кластером в целом. Для os error 3 используйте #20206 и #20048, для формулировки об отсутствии бинарника используйте #28392 и #28031, для падения плагина используйте #26440. Читайте официальный список изменений Codex, прежде чем обновляться: ищите номер тикета или слово «app-server» в заметках, а не обновляйтесь вслепую в надежде, что случайный релиз поможет. И держите CLI как базовую опору. Поскольку он не зависит от app-server Desktop, рабочий codex --version в терминале означает, что сломанное приложение Desktop представляет собой неудобство, а не блокер.

Сохраните это как codex-diag.ps1 и запускайте всякий раз, когда возвращается ошибка app-server. Скрипт собирает за один проход каждый сигнал, на который опираются решения выше:

# codex-diag.ps1 : collect the signals the app-server fixes depend on
Write-Host "== Installed packages =="
Get-AppxPackage *Codex* | Select-Object Name, Version, InstallLocation

Write-Host "== Profile path (non-ASCII breaks path resolution) =="
$env:USERPROFILE

Write-Host "== Stale versions on PATH =="
$env:PATH -split ';' | Select-String 'OpenAI.Codex'

Write-Host "== CLI on PATH? (your fallback) =="
where.exe codex 2>$null; codex --version 2>$null

Write-Host "== Recent errors in the state dir =="
Select-String -Path "$env:USERPROFILE\.codex\*.log" `
  -Pattern "os error 3|exited unexpectedly|defaultPrompt|websocket closed" `
  -ErrorAction SilentlyContinue | Select-Object -Last 10

Вывод говорит, какое решение применимо, без гаданий: две версии пакета означают Решение 1, не-ASCII профиль означает Решение 2, присутствующий но заблокированный бинарник означает Решение 3, отсутствующий бинарник означает Решение 4, а WARN о defaultPrompt означает Решение 5. Рабочий codex --version внизу означает, что можно прекращать отладку и переходить на CLI прямо сейчас.

FAQ

Блок faq во frontmatter содержит канонические ответы. Они охватывают, что означает os error 3, формулировку «Unable to locate the Codex CLI binary», помогает ли перезапуск, ловушку с не-ASCII именем пользователя, можно ли продолжать работать без приложения Desktop, исправлен ли уже баг и как убрать старые версии пакета из PATH.

Источники

• openai/codex#20206
• openai/codex#20048
• openai/codex#25671
• openai/codex#25886
• openai/codex#26440
• openai/codex#28031
• openai/codex#28392
• Codex CLI changelog
• ofox docs: Codex integration
• codex: command not found, 7 fixes
• Codex Desktop Not Showing Custom Models