Установка Codex несложна, по-настоящему легко застрять на подключении: где разместить API Key, как написать config.toml, в чём различия между Windows и macOS, почему VS Code не видит переменные из терминала, нужно ли фиксировать модель……

Если вы просто хотите как можно скорее запустить Codex, можно свести конфигурацию к трём значениям:

Provider: acedatacloud
Base URL: https://api.acedata.cloud/v1
API Key env: ACEDATACLOUD_API_KEY

После завершения Codex CLI, Desktop и расширение VS Code могут совместно использовать ~/.codex/config.toml, а модель можно выбирать непосредственно после запуска — не нужно постоянно менять конфигурацию подключения ради смены модели.

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

Подготовка

Перед началом убедитесь:

  • Вы зарегистрированы и вошли в Ace Data Cloud
  • Вы создали или имеете доступное приложение
  • На локальном компьютере установлены Node.js и npm
  • Вы можете использовать терминал или PowerShell
  • Вы готовы использовать хотя бы один из вариантов: Codex CLI, Codex Desktop или расширение VS Code

Шаг 1: получение Ace Data Cloud API Key

Откройте список приложений Ace Data Cloud, войдите в доступное приложение и скопируйте API Key.

Обратите внимание:

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

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

Шаг 2: установка Codex CLI

Установите Codex глобально через npm:

npm install -g @openai/codex

После установки выполните проверку:

codex --version

Если появляется сообщение, что команда не найдена, сначала убедитесь, что глобальный каталог исполняемых файлов npm добавлен в PATH, затем снова откройте терминал.

Если вы в основном используете VS Code, также можно установить опубликованное OpenAI расширение Codex:

code --install-extension openai.chatgpt

CLI и расширение VS Code используют общий файл конфигурации, поэтому рекомендуется сначала настроить Provider и переменную окружения, а затем запустить редактор для проверки.

Шаг 3: настройка переменной окружения API Key

macOS / Linux: текущий сеанс терминала

export ACEDATACLOUD_API_KEY="ваш API Key"

Эта команда действует только для текущей оболочки Shell и её дочерних процессов. После закрытия терминала переменная исчезнет.

macOS / Linux: постоянное действие

Если используется Zsh:

echo 'export ACEDATACLOUD_API_KEY="ваш API Key"' >> ~/.zshrc
source ~/.zshrc

Если используется Bash:

echo 'export ACEDATACLOUD_API_KEY="ваш API Key"' >> ~/.bashrc
source ~/.bashrc

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

Windows PowerShell

setx ACEDATACLOUD_API_KEY "ваш API Key"

После выполнения закройте и снова откройте PowerShell. setx не обновляет автоматически уже открытые процессы, поэтому существующий терминал и VS Code могут всё ещё не видеть новое значение.

Если требуется временно установить значение только в текущем сеансе PowerShell:

$env:ACEDATACLOUD_API_KEY="ваш API Key"

Шаг 4: создание или редактирование config.toml

Codex CLI, Desktop и расширение VS Code совместно используют следующий файл конфигурации:

  • macOS / Linux: ~/.codex/config.toml
  • Windows: %USERPROFILE%\.codex\config.toml

Если каталога не существует, сначала создайте его.

macOS / Linux:

mkdir -p ~/.codex

Затем добавьте:

model_provider = "acedatacloud"

[model_providers.acedatacloud]
name = "acedatacloud"
base_url = "https://api.acedata.cloud/v1"

[model_providers.acedatacloud.auth]
command = "sh"
args = ["-c", "echo $ACEDATACLOUD_API_KEY"]

Windows использует тот же Provider и Base URL, но команда аутентификации заменяется на PowerShell:

model_provider = "acedatacloud"

[model_providers.acedatacloud]
name = "acedatacloud"
base_url = "https://api.acedata.cloud/v1"

[model_providers.acedatacloud.auth]
command = "powershell"
args = ["-NoProfile", "-Command", "Write-Output $env:ACEDATACLOUD_API_KEY"]

Три имени в конфигурации должны строго совпадать:

  • model_provider = "acedatacloud"
  • [model_providers.acedatacloud]
  • [model_providers.acedatacloud.auth]

Base URL также должен полностью содержать /v1.

Шаг 5: запуск Codex и выбор модели

После сохранения конфигурации снова откройте терминал и выполните:

codex

После входа в Codex выполните:

/model

Убедитесь, что текущий Provider — acedatacloud, затем выберите модель из доступного списка.

В конфигурации подключения не обязательно фиксировать model. Разделение Provider и выбора модели позволяет сократить затраты на постоянное редактирование TOML при переключении моделей. Фактические модели и доступный диапазон могут обновляться, следует ориентироваться на /model и актуальный каталог платформы.

Шаг 6: проверка минимальным запросом

Не просите Codex сразу рефакторить весь репозиторий. Сначала отправьте простой запрос, результат которого можно быстро оценить, например:

Кратко опиши структуру каталогов текущего проекта, не изменяй никаких файлов.

Затем откройте Ace Data Cloud Usage History, убедитесь, что запрос поступил, и проверьте статус и расход.

Если минимальный запрос успешно выполнен, затем постепенно попробуйте чтение файлов, создание плана изменений, редактирование кода и запуск тестов.

Ключевые моменты настройки VS Code

Расширение VS Code будет читать тот же ~/.codex/config.toml, но возможность видеть API Key зависит от окружения процесса, в котором работает расширение.

После настройки полностью закройте и снова откройте VS Code. В macOS / Linux, если после запуска из графического интерфейса переменная по-прежнему не читается, можно выполнить из терминала, где уже установлен Key:

code .

При использовании следующих окружений следует настраивать переменную на стороне, где расширение фактически работает:

  • Remote SSH: удалённый хост
  • WSL: окружение WSL Linux
  • Dev Container: окружение контейнера
  • Codespaces или аналогичные удалённые окружения: соответствующий удалённый сеанс

Настройка переменной только в локальной Shell не гарантирует, что удалённое расширение автоматически её получит.

Ключевые моменты настройки Codex Desktop

Desktop и CLI совместно используют файл конфигурации, но графическое приложение не обязательно наследует временно выполненный в терминале export.

Если Desktop не видит Key:

  1. Установите переменную окружения как постоянную или системную
  2. Полностью закройте Desktop
  3. Перезапустите приложение
  4. Снова проверьте Provider и модель

Устранение распространённых ошибок

1. 401, Unauthorized или Incorrect API Key

Порядок проверки:

  1. Полностью ли скопирован API Key
  2. Является ли именем переменной окружения ACEDATACLOUD_API_KEY
  3. Был ли текущий процесс запущен после установки переменной
  4. Соответствует ли auth.command текущей операционной системе
  5. Действительны ли ещё учётные данные Не выводите полный Key в логи или чат. Можно проверить переменную, используя только проверку «существует ли она».

macOS / Linux：

if [ -n "$ACEDATACLOUD_API_KEY" ]; then echo "Key is set"; else echo "Key is missing"; fi

PowerShell：

if ($env:ACEDATACLOUD_API_KEY) { "Key is set" } else { "Key is missing" }

2. Provider не меняется на acedatacloud

Убедитесь в пути к файлу конфигурации и иерархии TOML. Распространённые ошибки включают:

  • имя файла указано как config.toml.txt
  • отредактирован каталог другого пользователя
  • имя таблицы написано иначе
  • ошибка в кавычках или формате массива
  • после сохранения клиент не был перезапущен

3. Сбой запроса к Base URL

Убедитесь, что адрес:

https://api.acedata.cloud/v1

Не пропускайте https:// или завершающий /v1, а также не используйте по ошибке адрес страницы консоли.

4. CLI работает, а VS Code — нет

Обычно это не проблема конфигурации Provider, а то, что процесс VS Code не считал переменную окружения. Запустите code . из терминала, где переменная уже установлена, или настройте системную переменную и полностью перезапустите VS Code.

5. Key не считывается в WSL, SSH или контейнере

Переменная окружения должна быть задана в среде, где фактически работает Codex или расширение. setx на хосте Windows не записывается автоматически в WSL; локальные переменные также не передаются автоматически на удалённый SSH-хост или в контейнер.

6. Не удаётся найти нужную модель

Не пытайтесь вручную угадать старый ID модели. Запустите /model, чтобы увидеть доступные в реальном времени варианты, и проверьте права приложения, баланс и текущий Provider.

7. Запрос приходит, но сложную задачу выполнить не удаётся

Сначала сузьте область задачи: попросите Codex только проанализировать, составить план, а затем постепенно разрешайте изменения и тестирование. Успешное подключение модели не означает, что все задачи репозитория должны быть выполнены за один раз; сложные изменения всё ещё требуют чётких критериев приёмки, тестирования и ручной проверки.

Рекомендуемый чек-лист проверки конфигурации

Перед отправкой первой официальной задачи подтвердите по пунктам:

  • Действительный API Key получен из списка приложений
  • Key сохранён в ACEDATACLOUD_API_KEY
  • Key не записан в Git-репозиторий
  • model_provider имеет значение acedatacloud
  • Base URL имеет значение https://api.acedata.cloud/v1
  • auth.command соответствует операционной системе
  • Codex или VS Code полностью перезапущен
  • В /model видны Provider и модель
  • Минимальный тестовый запрос выполнен успешно
  • В Usage History видна соответствующая запись вызова

Один Provider, меньше повторяющихся настроек

Суть этого способа подключения заключается не в том, чтобы написать ещё один фрагмент TOML, а в создании стабильных границ:

  • API Key управляется через переменные окружения
  • подключение Provider управляется через config.toml
  • модель выбирается в Codex в зависимости от задачи
  • записи вызовов и расход единообразно просматриваются в консоли Ace Data Cloud
  • CLI, Desktop и VS Code используют одну конфигурацию

Когда аутентификация, Provider и выбор модели чётко разделены, многие вопросы вроде «почему Codex снова не работает» можно быстро локализовать, не прибегая к повторному входу, переустановке или копированию нескольких конфигураций.

Откройте Центр конфигурации Codex, чтобы ознакомиться с официальными руководствами для разных клиентов, или перейдите в список приложений, чтобы получить API Key.

Справочные материалы