Codex

Настройка и использование AGTCloud в Codex CLI и Codex App.

Codex — агент программирования от OpenAI. Вы можете использовать Codex CLI в терминале или управлять проектами и задачами в настольном App. Настроив пользовательского поставщика моделей, вы можете подключить Codex к совместимой точке входа OpenAI Responses платформы AGTCloud.

Поддержка вызова инструментов, рассуждений, нескольких агентов и длина контекста зависят от модели. Выбирайте модель, доступную текущему ключу API и поддерживающую протокол Responses.

Подготовка

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

Подготовили терминал и локальный проект, который нужно открыть;
Зарегистрировались и вошли в AGTCloud;
Создали токен на странице API Keys;
Скопировали из каталога моделей ID модели, доступной текущему токену и поддерживающей Responses.

Установка Codex

Выберите способ установки для текущей среды.

curl -fsSL https://chatgpt.com/codex/install.sh | sh

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

codex --version

Настройка ключа API

Codex считывает ключ API из переменной окружения, заданной пользовательским Provider. В этом руководстве используется отдельная AGTCLOUD_API_KEY, чтобы не смешивать ключи OpenAI и других платформ.

Временная конфигурация

Следующие настройки действуют только в текущем сеансе терминала.

export AGTCLOUD_API_KEY="your-api-key"

Постоянная конфигурация

Для автоматического применения при каждом открытии терминала запишите переменную в конфигурацию shell или пользовательские переменные окружения Windows.

Откройте ~/.zshrc и добавьте:

export AGTCLOUD_API_KEY="your-api-key"

После сохранения загрузите конфигурацию:

source ~/.zshrc

Не записывайте ключ API в config.toml

В config.toml сохраняется только имя переменной окружения. Ключ API хранится локально открытым текстом в настройках окружения; используйте этот способ только на личном доверенном устройстве.

Настройка Provider AGTCloud

Пользовательская конфигурация Codex находится в ~/.codex/config.toml. Если файл уже существует, сначала сделайте резервную копию, затем добавьте Provider AGTCloud в существующую конфигурацию, не перезаписывая другие настройки.

mkdir -p ~/.codex

if [[ -f ~/.codex/config.toml ]]; then
    cp ~/.codex/config.toml ~/.codex/config.toml.backup
fi

Добавьте в ~/.codex/config.toml:

model_provider = "agtcloud"
model = "MODEL_ID"

[model_providers.agtcloud]
name = "AGTCloud"
base_url = "https://api.agtcloud.cn/v1"
env_key = "AGTCLOUD_API_KEY"
wire_api = "responses"

Параметр	Назначение
`model_provider`	Переключает поставщика моделей по умолчанию на AGTCloud
`model`	Задаёт ID модели для Codex
`base_url`	Направляет запросы Responses на адрес API AGTCloud, показанный на этой странице
`env_key`	Задаёт имя переменной окружения, содержащей ключ API
`wire_api`	Задаёт использование протокола OpenAI Responses

Provider должен находиться в пользовательской конфигурации

Файл .codex/config.toml в проекте может содержать настройки проекта, но не переопределяет model_provider и model_providers. Поместите приведённую конфигурацию Provider в ~/.codex/config.toml пользовательского каталога.

Выбор модели

MODEL_ID — заполнитель, который нужно заменить, а не настоящее название модели. Скопируйте из каталога моделей ID модели, доступной текущему ключу API и поддерживающей Responses, и в config.toml замените MODEL_ID.

В Codex CLI команда /model позволяет просматривать или менять модель. Для пользовательского Provider доступный набор зависит от версии Codex и текущего ключа API. Если нужная модель отсутствует, откройте config.toml и обновите model непосредственно в нём.

Использование Codex CLI

Переход в каталог проекта

cd /path/to/your/project

Запуск Codex

codex

Проверка текущей конфигурации

Выполните в Codex:

/status

Убедитесь, что текущие Provider, модель и конфигурационный файл соответствуют ожиданиям. Base URL должен совпадать с показанным на этой странице адресом API с /v1, без повторного /v1/v1.

Тест только для чтения

В тестовом проекте с README.md введите:

Прочитайте README.md и в трёх пунктах опишите назначение этого проекта. Не изменяйте никакие файлы.

Нормальный ответ подтверждает установление базового подключения. Этот шаг создаёт обычный расход API.

Использование Codex App

Перезапуск App

После сохранения ~/.codex/config.toml и переменных окружения полностью закройте Codex App и откройте его заново.

Открытие локального проекта

Переключитесь на Codex в настольном App и выберите тестовый проект без конфиденциального кода.

Проверка модели и подключения

Убедитесь, что текущая модель соответствует config.toml, затем проверьте её тем же заданием чтения README, что и в CLI.

Загрузка переменных окружения в App зависит от версии и способа запуска

Codex App использует локальную конфигурацию Codex, но загрузка переменных shell настольным приложением может различаться между версиями и ОС. Если CLI работает, а App не считывает ключ API, сначала полностью перезапустите App, затем проверьте пользовательскую конфигурацию и переменные окружения.

Частые вопросы

Симптом	Что проверить сначала	Решение
Команда `codex` не найдена	Установку и `PATH`	Откройте терминал заново, выполните `codex --version` и при необходимости повторите официальную команду установки
Ключ API не загружен	Действует ли `AGTCLOUD_API_KEY` в текущем процессе	Откройте терминал или App заново и повторно загрузите пользовательское окружение
Provider не применяется	Не записан ли он ошибочно в проектный `.codex/config.toml`	Перенесите `model_provider` и `model_providers` в `~/.codex/config.toml`
В пути запроса появляется `/v1/v1`	Не дополнен ли `base_url` лишним суффиксом	Используйте непосредственно показанный здесь `https://api.agtcloud.cn/v1`
Ответ `401`	Ключ API и переменные окружения	Используйте действующий ключ API и проверьте совпадение имени `env_key`
Ответ `403`	Права токена, доступ к модели и состояние аккаунта	Проверьте токен и доступные модели в консоли
Ответ `404`	Base URL, точку входа Responses и ID модели	Проверьте `base_url` и заново скопируйте ID модели, доступной текущему ключу
Модель отсутствует или недоступна	Видимость модели и поддержку Responses	Скопируйте полный ID из каталога моделей и выберите модель, вызываемую текущим ключом
CLI работает, но App не считывает конфигурацию	Версию App, путь конфигурации и переменные окружения	Полностью перезапустите App; сначала проверьте ту же пользовательскую конфигурацию через CLI
Некоторые расширенные возможности недоступны	Возможности целевой модели и текущую адаптацию	Сначала проверьте базовое задание только для чтения; расширенные возможности определяются фактическими результатами вызовов

Если причину найти не удаётся, запишите время запроса, API Base URL, ID модели, HTTP-статус и обезличенную ошибку, затем обратитесь к разделу ошибок и диагностики. Не отправляйте полный ключ API.