> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Руководство по использованию Codex CLI в терминале

> Codex 集成指南 - Ace Data Cloud

Codex CLI — это локальный программный агент с открытым исходным кодом от OpenAI, который работает в вашем терминале. Он может читать код, изменять файлы, выполнять команды, объяснять ошибки и помогать в выполнении повседневных задач разработки.

Codex CLI поддерживает настройку поставщиков моделей. Вы можете использовать его через совместимый прокси OpenAI Responses от Ace Data Cloud без необходимости отдельной подписки на официальный аккаунт OpenAI. После настройки Codex CLI будет отправлять запросы на `https://api.acedata.cloud/v1`.

## Процесс регистрации

Чтобы использовать Codex CLI, сначала перейдите в [Ace Data Cloud консоль](https://platform.acedata.cloud/console/applications) и получите ваш API Token для дальнейшего использования.

![](https://cdn.acedata.cloud/5hmkdg.jpg)

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

При первом запросе предоставляется бесплатный лимит, чтобы вы могли бесплатно опробовать сервис Codex CLI.

## Установка Codex CLI

Codex CLI поддерживает macOS, Linux, Windows и WSL. Вы можете установить его через npm или Homebrew (только для macOS).

### Установка через npm (рекомендуется)

Если у вас установлен Node.js, можно установить напрямую через npm. Требуется Node.js версии 18 или выше.

```bash theme={null}
npm install -g @openai/codex
```

### Установка через Homebrew (macOS)

Пользователи macOS могут установить через Homebrew:

```bash theme={null}
brew install --cask codex
```

### Проверка установки

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

```bash theme={null}
codex --version
```

Если появится сообщение `command not found`, скорее всего, текущий терминал ещё не загрузил обновлённый PATH. Закройте и откройте терминал снова или проверьте настройки PATH, указанные в выводе установки.

## Настройка Codex CLI

По умолчанию Codex CLI пытается подключиться к официальному сервису OpenAI. Чтобы использовать Ace Data Cloud, необходимо в конфигурационном файле Codex указать кастомного `model_provider` и поместить API Token в соответствующую переменную окружения.

### Шаг 1: Установка переменной окружения

Рекомендуется добавить API Token в конфигурационный файл вашей оболочки, например `~/.zshrc`, `~/.bashrc` или `~/.bash_profile`:

```bash theme={null}
export ACEDATACLOUD_API_KEY="{token}"
```

Замените `{token}` на ваш скопированный API Token из консоли Ace Data Cloud.

После этого откройте терминал заново или выполните команду `source` для немедленного применения:

```bash theme={null}
source ~/.zshrc
```

### Шаг 2: Редактирование конфигурационного файла Codex

Codex CLI использует глобальный конфигурационный файл `~/.codex/config.toml`. Если файла нет, создайте его:

```bash theme={null}
mkdir -p ~/.codex
touch ~/.codex/config.toml
```

Добавьте в `~/.codex/config.toml` следующий контент:

```toml theme={null}
model_provider = "acedatacloud"
model = "gpt-5"
model_reasoning_effort = "high"

[model_providers.acedatacloud]
name = "Ace Data Cloud"
base_url = "https://api.acedata.cloud/v1"
env_key = "ACEDATACLOUD_API_KEY"
wire_api = "responses"
```

Описание полей:

| Поле                                      | Описание                                                                      |
| ----------------------------------------- | ----------------------------------------------------------------------------- |
| `model_provider`                          | Имя поставщика по умолчанию, соответствует ключу в `[model_providers.<name>]` |
| `model`                                   | ID модели по умолчанию                                                        |
| `model_reasoning_effort`                  | Интенсивность рассуждений, обычно `low`, `medium` или `high`                  |
| `[model_providers.acedatacloud].base_url` | Адрес прокси Ace Data Cloud для OpenAI Responses                              |
| `[model_providers.acedatacloud].env_key`  | Имя переменной окружения с API Token для Codex CLI                            |
| `[model_providers.acedatacloud].wire_api` | Тип протокола, для OpenAI Responses должен быть `responses`                   |

### Очистка кеша официального входа OpenAI

Если вы ранее входили в Codex CLI через официальный аккаунт OpenAI, локально мог сохраниться статус входа (обычно в `~/.codex/auth.json`). Перед переключением на Ace Data Cloud рекомендуется очистить старый вход:

```bash theme={null}
codex logout
```

Если команда `codex logout` недоступна, можно удалить кеш вручную:

```bash theme={null}
rm -f ~/.codex/auth.json
```

Если вы никогда не входили в официальный аккаунт OpenAI, этот шаг можно пропустить.

### Запуск сессии

Перейдите в каталог вашего проекта и запустите Codex CLI:

```bash theme={null}
cd /path/to/your/project
codex
```

После появления интерфейса Codex можно вводить запросы, например:

```text theme={null}
Объясни структуру каталогов этого проекта
```

### Проверка конфигурации

В интерфейсе Codex CLI можно проверить текущую модель и поставщика:

```text theme={null}
/model
```

Вы должны увидеть, что модель принадлежит поставщику `acedatacloud`, например:

```text theme={null}
Model: gpt-5
Provider: acedatacloud
```

Если поставщик отличается от `acedatacloud`, значит конфигурация не применена. Проверьте, сохранён ли файл `~/.codex/config.toml` и доступна ли переменная окружения `ACEDATACLOUD_API_KEY` в текущем терминале:

```bash theme={null}
echo $ACEDATACLOUD_API_KEY
```

Также вы можете проверить историю запросов и информацию о расходах в [Ace Data Cloud консоли - История использования](https://platform.acedata.cloud/console/usages) и остаток лимита в [Ace Data Cloud консоли - Список приложений](https://platform.acedata.cloud/console/applications).

## Принцип работы

Codex CLI изначально использует протокол OpenAI Responses API. Ace Data Cloud предоставляет совместимый прокси по адресу `https://api.acedata.cloud/v1/responses`, поэтому Codex CLI не требует локального прокси или дополнительных плагинов.

Рабочий процесс:

1. Codex CLI читает `model_provider` из `~/.codex/config.toml` и загружает соответствующий блок `[model_providers.acedatacloud]`.
2. Codex CLI получает API Token из переменной окружения, указанной в `env_key` (`ACEDATACLOUD_API_KEY`).
3. Запросы по протоколу `wire_api = "responses"` отправляются на `base_url + /responses`, то есть `https://api.acedata.cloud/v1/responses`.
4. Ace Data Cloud проверяет API Token, лимиты и перенаправляет запросы на доступные каналы моделей.
5. После выполнения запроса платформа фиксирует использование и списывает соответствующий лимит.

Таким образом, вы продолжаете использовать оригинальную команду `codex` и родной интерфейс Codex CLI, меняя только базовый сервис модели на Ace Data Cloud.

## Настройка модели

Параметр `model` в `~/.codex/config.toml` определяет модель по умолчанию. OpenAI Responses сервис Ace Data Cloud поддерживает несколько моделей, наиболее популярные:

| Модель             | Описание                                                                      |
| ------------------ | ----------------------------------------------------------------------------- |
| `gpt-5`            | Рекомендуемая модель по умолчанию, подходит для большинства задач кодирования |
| `gpt-5-mini`       | Лёгкая и быстрая, подходит для простых задач                                  |
| `gpt-5.5`          | Обновлённая версия с улучшенными возможностями                                |
| `gpt-5.5-pro`      | Усиленная версия для сложных задач рассуждения                                |
| `gpt-4.1`          | Предыдущая основная модель                                                    |
| `o3`               | Модель с усиленным рассуждением, подходит для глубокого анализа               |
| `o4-mini-high-all` | Лёгкая модель для рассуждений                                                 |

Для временного переключения модели можно указать параметр при запуске:

```bash theme={null}
codex --model gpt-5-mini
```

Или изменить поле `model` в `~/.codex/config.toml` и перезапустить Codex CLI. Полный список моделей доступен в [документации Ace Data Cloud OpenAI сервиса](https://platform.acedata.cloud/documents/openai).

## Уровни доверия проекта

Codex CLI позволяет задавать разные уровни доверия для проектов, чтобы контролировать, какие действия агент может выполнять. Добавьте в конец `~/.codex/config.toml`:

```toml theme={null}
[projects."/path/to/trusted/project"]
trust_level = "trusted"

[projects."/path/to/untrusted/project"]
trust_level = "untrusted"
```

Описание уровней:

* `trusted`: агент имеет полный доступ, может выполнять команды и изменять файлы.
* `untrusted`: агент имеет ограниченные права, подходит для незнакомых проектов.

## Дополнительные ресурсы

* [Официальный репозиторий Codex CLI](https://github.com/openai/codex)
* [Документация Ace Data Cloud OpenAI сервиса](https://platform.acedata.cloud/documents/openai)
* [Ace Data Cloud консоль](https://platform.acedata.cloud/console/applications)