feat(clients): configure Codex Desktop with guarded user settings

.github/workflows/validate.yml

@@ -37,6 +37,9 @@ jobs:
       - name: Validate PowerShell syntax
         shell: powershell
         run: .\tests\windows\syntax.ps1
+      - name: Validate Codex Desktop configuration
+        shell: powershell
+        run: .\tests\windows\desktop-config.ps1
       - name: Run isolated installer smoke
         shell: powershell
         run: .\tests\windows\smoke.ps1

README.en.md

@@ -1,6 +1,6 @@
 # NeuroAPI for Codex CLI and Claude Code
 
-Public, auditable guided setup for routing local Codex CLI and Claude Code sessions through [NeuroAPI](https://neuroapi.host) on Windows and macOS. It configures the terminal launchers `codex-neuroapi` and `claude-neuroapi`; it does not configure or validate the Claude Desktop Code or Codex Desktop GUIs.
+Public, auditable guided setup for routing local Codex CLI and Claude Code sessions through [NeuroAPI](https://neuroapi.host) on Windows and macOS. It configures the terminal launchers `codex-neuroapi` and `claude-neuroapi`. With separate consent, it also configures **Codex Desktop** in the user-level `~/.codex/config.toml`. See the [Claude Desktop guide](https://neuroapi.host/docs/claude-desktop) for that application's own setup.
 
 [Русская версия](README.md)
 
@@ -23,16 +23,18 @@ Windows:
 1. [Download the agents ZIP](https://github.com/neurogen-dev/NeuroAPI/archive/refs/heads/agents.zip).
 2. Extract it and double-click `setup-windows.bat`.
 3. Paste the key into the masked PowerShell prompt.
-4. Open a new terminal and run `codex-neuroapi` or `claude-neuroapi`.
+4. If you use Codex Desktop, choose the optional Desktop setup and restart the app. Your original user config is backed up.
+5. Open a new terminal and run `codex-neuroapi` or `claude-neuroapi`.
 
 macOS:
 
 1. Download and extract the same ZIP.
 2. In the extracted directory, run `bash setup-macos.command`.
 3. Paste the key into the macOS Keychain prompt.
-4. Run `~/.local/bin/codex-neuroapi` or `~/.local/bin/claude-neuroapi`.
+4. If you use Codex Desktop, choose the optional Desktop setup and restart the app. Your original user config is backed up.
+5. Run `~/.local/bin/codex-neuroapi` or `~/.local/bin/claude-neuroapi`.
 
-The setup does not require administrator privileges, does not use `sudo`, and does not overwrite existing Codex, Claude Code, or shell configuration.
+The setup does not require administrator privileges or `sudo`. Codex Desktop integration edits the user config only after consent, with a guarded backup and conflict checks.
 
 ## Secret model
 
@@ -49,6 +51,7 @@ This prevents accidental plaintext disclosure. It does not protect a key from ma
 
 - In `codex-neuroapi`, run `/debug-config` and confirm the `neuroapi-host` profile and `https://neuroapi.host/v1/codex`.
 - In `claude-neuroapi`, run `/status` and confirm `https://neuroapi.host/v1/claude-code` plus `apiKeyHelper`.
+- For Codex Desktop, check a new local task, `https://codex.neuroapi.host/v1` in the user config, and the request in your NeuroAPI usage logs. Setup uses HTTP/SSE for this GUI integration.
 - Check current model IDs and pricing at [neuroapi.host/price](https://neuroapi.host/price).
 
 Each launcher fetches a fresh catalog scoped to the ordinary NeuroAPI key. Codex uses a private `model_catalog_json`; Claude receives a configured picker. There are no hardcoded default models. Tested minimum versions are Codex 0.158.0 and Claude Code 2.1.284. The Claude launcher limits initial output to 4096 tokens to bound quota reservation. Invalid, empty or unavailable catalogs stop launch instead of restoring stale lists. Organization policies and deliberate CLI overrides retain their documented precedence; these launchers do not support host-managed provider mode.
@@ -64,4 +67,6 @@ Claude Code also uses the `haiku` alias for background work. If no recommended H
 - [Troubleshooting](docs/troubleshooting.md)
 - [Codex guide](https://neuroapi.host/codex-api)
 - [Claude Code guide](https://neuroapi.host/claude-code)
+- [Codex Desktop guide](https://neuroapi.host/docs/codex-desktop)
+- [Claude Desktop Code guide](https://neuroapi.host/docs/claude-desktop)
 - [NeuroAPI documentation](https://neuroapi.host/docs/getting-started)

README.md

@@ -6,7 +6,7 @@
 
 Открытые установщики для подключения [Codex CLI](https://developers.openai.com/codex/cli/) и [Claude Code](https://code.claude.com/docs/en/overview) к [NeuroAPI](https://neuroapi.host) на Windows и macOS.
 
-Пакет настраивает **клиенты в терминале** через команды `codex-neuroapi` и `claude-neuroapi`. Настройки Claude Desktop Code и Codex Desktop этим установщиком не изменяются; работу этих GUI с NeuroAPI он не подтверждает.
+Пакет настраивает **клиенты в терминале** через команды `codex-neuroapi` и `claude-neuroapi`. При отдельном согласии он также подключает **Codex Desktop** через пользовательский `~/.codex/config.toml`. Claude Desktop настраивается в самом приложении по [отдельной инструкции](https://neuroapi.host/docs/claude-desktop).
 
 NeuroAPI — российский AI API-сервис: единый доступ к моделям OpenAI, Anthropic Claude, Google Gemini, DeepSeek, генерации изображений и видео с оплатой в рублях. Проект работает от российского ООО, инфраструктура сервиса размещена в РФ. Актуальные модели и цены всегда проверяйте в [живом каталоге](https://neuroapi.host/price).
 
@@ -31,7 +31,8 @@ NeuroAPI — российский AI API-сервис: единый доступ
 1. [Скачайте ZIP с установщиками](https://github.com/neurogen-dev/NeuroAPI/archive/refs/heads/agents.zip) и распакуйте его.
 2. Дважды щёлкните `setup-windows.bat`.
 3. Вставьте API-ключ в скрытый запрос PowerShell.
-4. Откройте новый терминал и запустите:
+4. Если используете Codex Desktop, ответьте «да» на отдельный вопрос установщика и перезапустите приложение. Установщик создаст резервную копию вашего пользовательского конфига.
+5. Откройте новый терминал и запустите:
 
 ```powershell
 codex-neuroapi
@@ -51,7 +52,8 @@ bash setup-macos.command
 ```
 
 4. Вставьте API-ключ в защищённый запрос macOS Keychain.
-5. Запустите:
+5. Если используете Codex Desktop, ответьте «да» на отдельный вопрос установщика и перезапустите приложение. Установщик создаст резервную копию вашего пользовательского конфига.
+6. Запустите:
 
 ```bash
 ~/.local/bin/codex-neuroapi
@@ -69,7 +71,8 @@ bash setup-macos.command
 | Codex | отдельный `~/.codex/neuroapi-host.config.toml` | отдельный `~/.codex/neuroapi-host.config.toml` |
 | Claude Code | отдельный installer-owned JSON через `--settings` | отдельный installer-owned JSON через `--settings` |
 | Получает ключ | command-backed auth helper | `apiKeyHelper` / Keychain helper |
-| Существующие конфиги | не перезаписываются | не перезаписываются |
+| Codex Desktop по согласию | пользовательский `config.toml`, DPAPI helper, каталог доступных моделей | пользовательский `config.toml`, Keychain helper, каталог доступных моделей |
+| Существующий `config.toml` | резервная копия и атомарное изменение только по согласию; конфликт останавливает установку | резервная копия и атомарное изменение только по согласию; конфликт останавливает установку |
 
 Установщик отправляет ключ только в NeuroAPI для проверки доступных моделей; платной генерации при настройке нет. При запуске `codex-neuroapi` или `claude-neuroapi` запускатель вновь получает актуальный каталог с `https://neuroapi.host`, затем клиент использует API при ваших запросах.
 
@@ -89,12 +92,14 @@ Windows:
 
 - `%LOCALAPPDATA%\NeuroAPIAgents\` — helper, Claude settings, DPAPI-ciphertext и launchers;
 - `%USERPROFILE%\.codex\neuroapi-host.config.toml` — отдельный профиль Codex;
+- `%USERPROFILE%\.codex\config.toml` — только при согласии на Codex Desktop; исходный файл хранится в installer-owned каталоге;
 - `%LOCALAPPDATA%\NeuroAPIAgents\bin` — одна запись в пользовательском `PATH`.
 
 macOS:
 
 - `~/.local/share/neuroapi-agents/` — helper и Claude settings;
 - `~/.codex/neuroapi-host.config.toml` — отдельный профиль Codex;
+- `~/.codex/config.toml` — только при согласии на Codex Desktop; исходный файл хранится в installer-owned каталоге;
 - `~/.local/bin/codex-neuroapi` и `~/.local/bin/claude-neuroapi`;
 - Keychain item `host.neuroapi.agents.api-key`.
 
@@ -127,6 +132,7 @@ Claude Code обращается к alias `haiku` и в фоновых зада
 - macOS: `./uninstall-macos.command`.
 
 Uninstaller удаляет только installer-owned файлы и локально сохранённый ключ. Удалённый ключ через этот пакет восстановить нельзя.
+Если после установки вы изменили `~/.codex/config.toml`, удаление остановится до удаления helper и ключа: это сохраняет работоспособность вашей конфигурации. Сначала вручную разберите изменения и повторите удаление.
 
 ## Документация
 
@@ -135,6 +141,8 @@ Uninstaller удаляет только installer-owned файлы и локал
 - [Решение проблем](docs/troubleshooting.md)
 - [Codex через NeuroAPI](https://neuroapi.host/codex-api)
 - [Claude Code через NeuroAPI](https://neuroapi.host/claude-code)
+- [Codex Desktop](https://neuroapi.host/docs/codex-desktop)
+- [Claude Desktop Code](https://neuroapi.host/docs/claude-desktop)
 - [OpenAI-совместимый API](https://neuroapi.host/openai-compatible-api)
 - [Модели и цены](https://neuroapi.host/price)
 

docs/manual-setup.md

@@ -45,6 +45,12 @@ Codex 0.158.0 по умолчанию добавляет к каждому за
 
 Project `.codex/config.toml` не подходит для provider/auth redirect: актуальный Codex игнорирует там `model_provider` и `model_providers` по соображениям безопасности.
 
+## Codex Desktop (по отдельному согласию)
+
+Установщик предлагает включить пользовательский Codex Desktop. В этом случае он сохраняет точную исходную копию `~/.codex/config.toml`, затем устанавливает в нём `model_provider = "neuroapi_agents"`, `model_catalog_json` с моделями, доступными введённому ключу, и подходящую модель по умолчанию. Провайдер использует `https://codex.neuroapi.host/v1`, Responses API, HTTP/SSE (`supports_websockets = false`) и тот же защищённый DPAPI/Keychain helper. Отдельный профиль CLI остаётся независимым.
+
+Если в исходном файле есть конфликтующий провайдер, необычная форма root-настроек, неверный TOML либо файл изменился во время установки, setup останавливается без перезаписи. Повторная установка сохраняет первоначальную копию. При удалении проверяется хеш конфигурации: если пользователь изменил файл после setup, uninstaller не удаляет helper и ключ, чтобы не сломать действующую настройку. После установки перезапустите Codex Desktop и проверьте новую локальную задачу; полная инструкция: [Codex Desktop](https://neuroapi.host/docs/codex-desktop).
+
 ## HTTP/SSE для диагностики
 
 Если соединение WebSocket блокируется вашей сетью, в секции `[model_providers.neuroapi]` созданного профиля замените `supports_websockets = true` на `supports_websockets = false`. Base URL остаётся `https://neuroapi.host/v1/codex`, auth helper и key storage не меняются. При повторном запуске setup управляемый профиль снова получит настройку по умолчанию `true`.
@@ -77,6 +83,7 @@ Project `.codex/config.toml` не подходит для provider/auth redirect
 - Claude settings: `%LOCALAPPDATA%\NeuroAPIAgents\config\claude-settings.json`;
 - launchers: `%LOCALAPPDATA%\NeuroAPIAgents\bin`;
 - Codex profile: `%USERPROFILE%\.codex\neuroapi-host.config.toml`.
+- Codex Desktop (опционально): `%USERPROFILE%\.codex\config.toml`, резервная копия и каталог в `%LOCALAPPDATA%\NeuroAPIAgents\config`.
 
 Setup добавляет только launcher directory в пользовательский `PATH`.
 
@@ -87,6 +94,7 @@ Setup добавляет только launcher directory в пользовате
 - Claude settings: `~/.local/share/neuroapi-agents/config/claude-settings.json`;
 - launchers: `~/.local/bin/codex-neuroapi`, `~/.local/bin/claude-neuroapi`;
 - Codex profile: `~/.codex/neuroapi-host.config.toml`;
+- Codex Desktop (опционально): `~/.codex/config.toml`, резервная копия и каталог в `~/.local/share/neuroapi-agents/config`;
 - Keychain service: `host.neuroapi.agents.api-key`.
 
 Setup не меняет `.zprofile`, `.zshrc`, `.bash_profile` или системный `PATH`.

docs/troubleshooting.md

@@ -1,6 +1,12 @@
 # Решение проблем
 
-Эти инструкции относятся к терминальным `codex-neuroapi` и `claude-neuroapi`. Запуск тех же моделей в Codex Desktop или вкладке Code приложения Claude Desktop требует отдельной настройки и проверки GUI.
+Терминальные launchers и графические приложения читают разные настройки. Codex Desktop можно подключить отдельным согласием в установщике или [вручную](https://neuroapi.host/docs/codex-desktop); Claude Desktop настраивается в [официальной форме приложения](https://neuroapi.host/docs/claude-desktop).
+
+## Codex Desktop обращается к `chatgpt.com`
+
+Проверьте пользовательский `~/.codex/config.toml`: `model_provider = "neuroapi_agents"`, `base_url = "https://codex.neuroapi.host/v1"`, `supports_websockets = false`. Перезапустите приложение и создайте **новую локальную** задачу. Старые задачи и облачные функции могут сохранять прежний маршрут. Если вы пропустили предложение установщика, запустите setup заново и согласитесь на подключение Desktop.
+
+Если удаление останавливается из-за изменения `config.toml`, сначала сравните текущий файл с резервной копией в каталоге установщика. Это защищает ваши правки и сохраняет key helper до ручного разбора.
 
 ## `codex-neuroapi` или `claude-neuroapi` не найдены
 

scripts/macos/common.sh

@@ -38,6 +38,14 @@ codex_home() {
   fi
 }
 
+desktop_codex_home() {
+  if is_test_mode && [[ -n "${NEUROAPI_AGENTS_DESKTOP_CODEX_HOME:-}" ]]; then
+    printf '%s\n' "$NEUROAPI_AGENTS_DESKTOP_CODEX_HOME"
+  else
+    printf '%s\n' "$HOME/.codex"
+  fi
+}
+
 launcher_root() {
   if is_test_mode && [[ -n "${NEUROAPI_AGENTS_BIN_ROOT:-}" ]]; then
     printf '%s\n' "$NEUROAPI_AGENTS_BIN_ROOT"