> ## 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, потрібно вказати власного `model_provider` у конфігураційному файлі Codex та додати API Token у відповідну змінну середовища.

### Крок 1: Встановлення змінної середовища

Рекомендується додати API Token у конфігураційний файл вашого Shell, наприклад `~/.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`                                   | Ідентифікатор моделі за замовчуванням                                                  |
| `model_reasoning_effort`                  | Рівень складності логіки: `low`, `medium`, `high`                                      |
| `[model_providers.acedatacloud].base_url` | Адреса проксі OpenAI Responses від Ace Data Cloud                                      |
| `[model_providers.acedatacloud].env_key`  | Назва змінної середовища для API Token                                                 |
| `[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` збережений правильно, а також чи доступна змінна середовища:

```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, ліміт та пересилає запит до відповідного upstream-моделю.
5. Після виконання платформа фіксує використання та списує відповідний ліміт.

Таким чином, ви користуєтеся оригінальним інтерфейсом Codex CLI, але з моделями Ace Data Cloud.

## Налаштування моделей

Поле `model` у `~/.codex/config.toml` визначає модель за замовчуванням. Ace Data Cloud OpenAI Responses підтримує кілька моделей, найпопулярніші:

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

Для тимчасової зміни моделі можна вказати параметр при запуску Codex:

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

Або змінити поле `model` у `~/.codex/config.toml` та перезапустити Codex. Повний список моделей доступний у [документації 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)