> ## 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 для VS Code

> Codex 集成指南 - Ace Data Cloud

Codex — це програмний агент від OpenAI. Окрім термінального CLI, він також пропонує розширення для VS Code, яке дозволяє спілкуватися в бічній панелі редактора, читати файли, посилатися на контекст, генерувати зміни та переглядати їх.

У цій статті описано, як налаштувати та використовувати розширення Codex у VS Code через сумісний проксі OpenAI Responses від Ace Data Cloud. Розширення Codex для VS Code та CLI Codex використовують одну й ту ж локальну систему конфігурації, тому достатньо вказати `~/.codex/config.toml`, щоб він звертався до Ace Data Cloud за адресою `https://api.acedata.cloud/v1`.

## Процес реєстрації

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

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

Якщо ви ще не увійшли або не зареєстровані, вас автоматично перенаправить на сторінку входу, де можна зареєструватися або увійти. Після входу ви повернетесь на поточну сторінку.

При першому запиті вам нададуть безкоштовний ліміт для ознайомлення з сервісом Codex.

## Встановлення розширення Codex

У маркетплейсі VS Code знайдіть розширення `Codex` та встановіть **Codex - OpenAI's coding agent** від OpenAI. Його Marketplace ID:

```text theme={null}
openai.chatgpt
```

Також можна встановити через командний рядок:

```bash theme={null}
code --install-extension openai.chatgpt
```

Після встановлення перезапустіть або перезавантажте VS Code. Якщо не бачите пункту Codex, відкрийте командну панель (macOS: `Cmd+Shift+P`, Windows/Linux: `Ctrl+Shift+P`) та виконайте:

```text theme={null}
Codex: Open Codex Sidebar
```

За замовчуванням Codex з’явиться у правій бічній панелі VS Code. Ви також можете перетягнути його у ліву панель Activity Bar.

## Встановлення Codex CLI (для перевірки)

Офіційна документація вказує, що розширення Codex для VS Code та CLI Codex використовують одну систему конфігурації. Щоб перевірити API Token і доступність моделей перед налаштуванням VS Code, рекомендується встановити CLI Codex.

Один із рекомендованих способів — встановлення через npm, потрібен Node.js версії 18 або вище:

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

Користувачі macOS можуть встановити через Homebrew:

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

Після встановлення перевірте доступність команди:

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

Якщо плануєте користуватися лише розширенням VS Code, цей крок можна пропустити; конфігурація `~/.codex/config.toml` буде однаковою.

## Налаштування API Ace Data Cloud

Розширення Codex для VS Code та CLI Codex використовують спільний файл конфігурації. За замовчуванням Codex пропонує увійти в офіційний OpenAI акаунт або вказати офіційний API Key. Щоб перейти на Ace Data Cloud, потрібно налаштувати API Token і файл `~/.codex/config.toml`.

### Крок 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
```

Якщо VS Code вже відкритий, перезапустіть або перезавантажте його, щоб розширення прочитало нову змінну середовища.

### Крок 2: Редагування конфігураційного файлу Codex

Файл користувацьких налаштувань Codex знаходиться за адресою `~/.codex/config.toml`. Якщо його немає, створіть:

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

Запишіть у файл таку конфігурацію:

```toml theme={null}
model_provider = "acedatacloud"
model = "gpt-5"
model_reasoning_effort = "high"
approval_policy = "on-request"
sandbox_mode = "workspace-write"

[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.acedatacloud]`                    |
| `model`                  | ID моделі за замовчуванням                                                                             |
| `model_reasoning_effort` | Рівень інтенсивності роздумів, типові значення: `low`, `medium`, `high`                                |
| `approval_policy`        | Політика підтвердження перед виконанням команд, для щоденного використання рекомендується `on-request` |
| `sandbox_mode`           | Права пісочниці під час виконання команд Codex, для розробки рекомендується `workspace-write`          |
| `base_url`               | Адреса OpenAI-сумісного API Ace Data Cloud                                                             |
| `env_key`                | Назва змінної середовища для зчитування API Token                                                      |
| `wire_api`               | Тип протоколу, для OpenAI Responses має бути `responses`                                               |

Також можна відкрити цей файл безпосередньо у VS Code через іконку шестерні у верхньому правому куті розширення, вибравши **Codex Settings > Open config.toml**.

### Конфігурація на рівні проекту

Якщо потрібно, щоб певний проект використовував інші налаштування, створіть у корені проекту файл `.codex/config.toml`. Codex віддаватиме перевагу цьому файлу, якщо проект позначений як trusted.

Приклад:

```toml theme={null}
model = "gpt-5-mini"
model_reasoning_effort = "medium"
```

Рекомендується зберігати особисті токени у змінних середовища, а не у файлах проекту. Також варто обдумати, чи варто додавати `.codex/config.toml` до репозиторію, залежно від політики команди.

## Очищення кешу OpenAI логіну

Якщо раніше ви входили в офіційний OpenAI акаунт через розширення Codex, локально може зберігатися стан входу. Перед переходом на проксі Ace Data Cloud виконайте у терміналі:

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

Якщо команда недоступна, можна видалити кеш вручну:

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

Після цього перезапустіть або перезавантажте VS Code.

## Основне використання

Після налаштування відкрийте панель Codex у лівій або правій частині VS Code і введіть запит. Наприклад:

```text theme={null}
Поясни структуру каталогів поточного проекту та вкажи основний вхідний файл.
```

Розширення Codex може використовувати файли редактора та виділений код як контекст. Ви також можете посилатися на файли у запиті за допомогою `@`, наприклад:

```text theme={null}
Звернись до @src/App.vue, допоможи розбити цю сторінку на більш чіткі компоненти.
```

Якщо виділити фрагмент коду, можна через командну панель виконати:

```text theme={null}
Codex: Add to Codex Thread
```

або

```text theme={null}
Codex: Add File to Codex Thread
```

щоб додати весь файл до контексту.

## Зміна моделі та інтенсивності роздумів

Розширення Codex для VS Code підтримує перемикання моделей у селекторі під полем вводу, а також регулювання `reasoning effort`. При використанні кастомного провайдера Ace Data Cloud найкраще спочатку вказати модель за замовчуванням у `~/.codex/config.toml`, а потім за потреби переключатися у інтерфейсі. Рекомендовані налаштування:

| Сценарій                                | Рекомендована модель        | Інтенсивність роздумів |
| --------------------------------------- | --------------------------- | ---------------------- |
| Щоденне читання коду та невеликі зміни  | `gpt-5-mini`                | `medium`               |
| Звичайні завдання розробки              | `gpt-5`                     | `high`                 |
| Складний рефакторинг та глибокий аналіз | `gpt-5.5` або `gpt-5.5-pro` | `high`                 |
| Завдання з підсиленим розумінням        | `o3`                        | `high`                 |

Якщо у інтерфейсі немає потрібної моделі, змініть поле `model` у `~/.codex/config.toml` та перезапустіть або перезавантажте VS Code. Повний список моделей доступний у [документації Ace Data Cloud OpenAI](https://platform.acedata.cloud/documents/openai).

## Вибір робочого режиму

Розширення Codex підтримує різні робочі режими. Основні:

| Режим                 | Сценарій використання                                                                                        |
| --------------------- | ------------------------------------------------------------------------------------------------------------ |
| `Chat`                | Обговорення, пояснення коду, планування без прямого редагування файлів                                       |
| `Agent`               | Дозволяє Codex читати файли, змінювати код, запускати необхідні команди; рекомендовано для щоденної розробки |
| `Agent (Full Access)` | Дає розширені права та доступ до мережі, підходить, якщо ви усвідомлюєте ризики                              |

Для щоденного використання рекомендується режим `Agent` з політикою підтвердження `approval_policy = "on-request"`. Це означає, що Codex перед виконанням чутливих команд, доступом за межі робочої області або мережею запитає підтвердження.

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

Спершу можна перевірити роботу Codex через термінал з тією ж конфігурацією:

```bash theme={null}
codex exec --model gpt-5-mini "Reply with exactly: ADC_Codex_OK"
```

Якщо все налаштовано правильно, отримаєте відповідь:

```text theme={null}
ADC_Codex_OK
```

Потім у VS Code відкрийте панель Codex і задайте просте питання:

```text theme={null}
Одним реченням опиши призначення поточної робочої області.
```

Також можна переглянути історію запитів і витрати у [Ace Data Cloud консолі - Історія використання](https://platform.acedata.cloud/console/usages) та залишок ліміту у [Ace Data Cloud консолі - Список додатків](https://platform.acedata.cloud/console/applications).

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

Розширення Codex для VS Code не має окремої системи конфігурації моделей. Воно запускає локальний Codex CLI та використовує спільний конфігураційний шар:

1. Розширення запускає Codex і читає користувацький файл `~/.codex/config.toml`.
2. Якщо проект позначено як trusted і в ньому є `.codex/config.toml`, завантажується також проектна конфігурація.
3. Якщо `model_provider` встановлено в `acedatacloud`, Codex бере API Token зі змінної `ACEDATACLOUD_API_KEY`.
4. Запити надсилаються через протокол OpenAI Responses на `https://api.acedata.cloud/v1/responses`.
5. Ace Data Cloud перевіряє автентичність, ліміти, пересилає запити та логуює використання.

Отже, CLI у терміналі та розширення VS Code зазвичай налаштовуються один раз. Після успішної перевірки в терміналі розширення автоматично використовує ту саму конфігурацію.

## Додаткова інформація

* [Офіційна документація Codex IDE extension](https://developers.openai.com/codex/ide)
* [Налаштування Codex IDE extension](https://developers.openai.com/codex/ide/settings)
* [Основи конфігурації Codex CLI](https://developers.openai.com/codex/config-basic)
* [Документація Ace Data Cloud OpenAI сервісу](https://platform.acedata.cloud/documents/openai)