> ## 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 через прокси-совместимый API OpenAI Responses, предоставляемый Ace Data Cloud. Расширение Codex для VS Code и CLI используют одну и ту же локальную систему конфигурации, поэтому достаточно указать `~/.codex/config.toml`, чтобы перенаправить работу Codex в VS Code на `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. Его ID в Marketplace:

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

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

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

После установки перезапустите или перезагрузите VS Code. Если вы не видите раздела Codex, откройте командную палитру (`Cmd+Shift+P` на macOS, `Ctrl+Shift+P` на Windows/Linux), найдите и выполните команду:

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

По умолчанию расширение появится в правой боковой панели VS Code. Также его можно перетащить в левую панель Activity Bar.

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

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

Один из рекомендуемых способов — установка через 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, этот шаг можно пропустить — конфигурация будет использоваться одна и та же.

## Настройка API Ace Data Cloud

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

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

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

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

где `{token}` — это ваш API Token, скопированный из панели Ace Data Cloud.

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

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

Если VS Code уже запущен, перезапустите или перезагрузите его, чтобы расширение прочитало новые переменные окружения.

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

Файл конфигурации пользователя для 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`                  | Идентификатор модели по умолчанию                                             |
| `model_reasoning_effort` | Уровень рассуждения: `low`, `medium`, `high`                                  |
| `approval_policy`        | Политика подтверждения перед выполнением команд: рекомендуется `on-request`   |
| `sandbox_mode`           | Режим песочницы для выполнения команд: рекомендуется `workspace-write`        |
| `base_url`               | Адрес API Ace Data Cloud, совместимый с OpenAI                                |
| `env_key`                | Название переменной окружения для API Token                                   |
| `wire_api`               | Тип протокола, для Response API обязательно `responses`                       |

Также можно открыть конфигурацию через значок шестеренки в правом верхнем углу расширения и выбрать **Codex Settings > Open config.toml**.

### Проектные настройки

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

Пример:

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

Рекомендуется хранить в конфигурации только токен и параметры, не вставляя их в репозиторий. Проектные `.codex/config.toml` также стоит решать в зависимости от команды.

## Очистка кеша авторизации OpenAI

Если ранее вы входили в OpenAI через расширение, локально может сохраниться авторизация. Перед переключением на прокси Ace Data Cloud выполните:

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

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

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

После этого перезапустите или перезагрузите VS Code.

## Основное использование

После настройки откройте панель Codex в левом или правом краю VS Code и вводите запросы. Например:

```text theme={null}
Объясни структуру текущего проекта и укажи основные входные файлы.
```

Расширение может использовать файлы и выделенный код как контекст. Можно также сослаться на файл с помощью `@`, например:

```text theme={null}
Обратись к @src/App.vue и помоги разбить этот компонент на более ясные части.
```

Если выделена часть кода, можно через командную палитру выполнить:

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

или

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

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

## Переключение моделей и уровня рассуждения

В расширении есть переключатель моделей и настройка уровня reasoning, расположенные под полем ввода. При использовании Ace Data Cloud рекомендуется сначала задать модель по умолчанию в `~/.codex/config.toml`, а затем при необходимости переключать через интерфейс.

Рекомендуемые сценарии:

| Сценарий                                    | Модель                      | Уровень рассуждения |
| ------------------------------------------- | --------------------------- | ------------------- |
| Повседневное чтение кода и небольшие правки | `gpt-4.1-mini`              | `medium`            |
| Обычная разработка                          | `gpt-5`                     | `high`              |
| Сложные рефакторинги и глубокое рассуждение | `gpt-5.5` или `gpt-5.5-pro` | `high`              |
| Задачи с усиленным рассуждением             | `o3`                        | `high`              |

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

## Выбор режима работы

Расширение поддерживает разные режимы работы:

| Режим                 | Описание                                                                                 |
| --------------------- | ---------------------------------------------------------------------------------------- |
| `Chat`                | Общение, объяснение, планирование, без прямых изменений файлов                           |
| `Agent`               | Чтение файлов, изменение кода, запуск команд — рекомендуется для повседневной разработки |
| `Agent (Full Access)` | Расширенные права и доступ к сети, подходит для сценариев с высоким риском               |

Рекомендуется использовать `Agent` с политикой подтверждения `on-request`. Тогда при выполнении чувствительных команд или обращении за пределы рабочей области расширение будет запрашивать подтверждение.

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

Для проверки можно выполнить в терминале:

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

При успешной настройке ответ будет:

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

Затем в панели Codex в VS Code задайте вопрос:

```text theme={null}
Опишите в одном предложении назначение текущей рабочей области.
```

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

## Как работает

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

1. Расширение запускает Codex CLI и читает `~/.codex/config.toml`.
2. Если проект доверен и есть `.codex/config.toml`, оно дополнительно загружает проектные настройки.
3. При `model_provider = "acedatacloud"` API Token читается из `ACEDATACLOUD_API_KEY`.
4. Запросы отправляются через протокол Responses API по адресу `https://api.acedata.cloud/v1/responses`.
5. Ace Data Cloud проверяет авторизацию, лимиты и перенаправляет запросы, ведет учет использования.

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

## Подробнее

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