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

# Конфигурация Codex/Windsurf

> Настройка Codex и Windsurf для использования MegaLLM

Codex и Windsurf используют формат конфигурации TOML и поддерживают только конфигурацию системного уровня (глобальную). CLI автоматически определяет, какой вариант у вас установлен.

<Note>
  Windsurf - это вариант Codex с расширенными функциями. Конфигурация идентична для обоих.
</Note>

## Файл конфигурации

**Расположение**: `~/.codex/config.toml`

```toml theme={null}
model_provider = "megallm"
model = "gpt-5"

[model_providers.megallm]
name = "OpenAI using Chat Completions"
base_url = "https://ai.megallm.io/v1"
env_key = "MEGALLM_API_KEY"
query_params = {}

[tools]
web_search = true
file_browser = true
```

<Warning>
  **Codex/Windsurf поддерживает только конфигурацию системного уровня.** Конфигурация уровня проекта недоступна.
</Warning>

## Переменная окружения

Конфигурация ссылается на переменную окружения для API ключа:

```bash theme={null}
export MEGALLM_API_KEY="sk-mega-your-api-key-here"
```

Это добавляется в файл конфигурации вашей оболочки:

* `~/.bashrc` (bash)
* `~/.zshrc` (zsh)
* `~/.config/fish/config.fish` (fish)
* Профиль PowerShell (Windows)

### Проверка переменной окружения

```bash theme={null}
echo $MEGALLM_API_KEY
# Вывод: sk-mega-your-api-key-here
```

## Ручная настройка

Если вы предпочитаете не использовать CLI:

```bash theme={null}
# 1. Создать каталог
mkdir -p ~/.codex

# 2. Создать файл конфигурации
cat > ~/.codex/config.toml << 'EOF'
model_provider = "megallm"
model = "gpt-5"

[model_providers.megallm]
name = "OpenAI using Chat Completions"
base_url = "https://ai.megallm.io/v1"
env_key = "MEGALLM_API_KEY"
query_params = {}

[tools]
web_search = true
file_browser = true
EOF

# 3. Добавить переменную окружения в конфигурацию оболочки
echo 'export MEGALLM_API_KEY="your-api-key"' >> ~/.bashrc

# 4. Перезагрузить оболочку
source ~/.bashrc
```

## Опции конфигурации

### Выбор модели

Измените модель по умолчанию в конфигурации:

```toml theme={null}
model = "claude-opus-4-1-20250805"  # или любая поддерживаемая модель
```

**Доступные модели:**

* `gpt-5` - Последняя модель GPT
* `gpt-4` - GPT-4
* `gpt-4o` - GPT-4 Optimized
* `claude-opus-4-1-20250805` - Claude Opus
* `claude-sonnet-4` - Claude Sonnet
* `gemini-2.5-pro` - Gemini Pro
* Смотрите [Каталог моделей](/ru/home/models) для полного списка

### Настройки инструментов

Включите или отключите интегрированные инструменты:

```toml theme={null}
[tools]
web_search = true      # Включить возможность веб-поиска
file_browser = true    # Включить браузер файлов
terminal = true        # Включить доступ к терминалу
code_execution = true  # Включить выполнение кода
```

### Расширенная конфигурация

```toml theme={null}
model_provider = "megallm"
model = "gpt-5"
temperature = 0.7
max_tokens = 4096
top_p = 0.9

[model_providers.megallm]
name = "OpenAI using Chat Completions"
base_url = "https://ai.megallm.io/v1"
env_key = "MEGALLM_API_KEY"
query_params = {}

[tools]
web_search = true
file_browser = true
terminal = true

[ui]
theme = "dark"
font_size = 14
show_line_numbers = true
```

## Множественные API ключи

Если вам нужны разные API ключи для разных целей:

### Использование переменных окружения

```bash theme={null}
# Ключ для разработки
export MEGALLM_API_KEY="sk-mega-dev-key"

# Производственный ключ
export MEGALLM_API_KEY_PROD="sk-mega-prod-key"
```

### Переключение конфигураций

```bash theme={null}
# Создать резервную копию текущей конфигурации
cp ~/.codex/config.toml ~/.codex/config.toml.backup

# Конфигурация для разработки
cat > ~/.codex/config.toml.dev << 'EOF'
model_provider = "megallm"
model = "gpt-4o-mini"

[model_providers.megallm]
base_url = "https://ai.megallm.io/v1"
env_key = "MEGALLM_API_KEY_DEV"
EOF

# Производственная конфигурация
cat > ~/.codex/config.toml.prod << 'EOF'
model_provider = "megallm"
model = "gpt-5"

[model_providers.megallm]
base_url = "https://ai.megallm.io/v1"
env_key = "MEGALLM_API_KEY_PROD"
EOF

# Переключить на разработку
cp ~/.codex/config.toml.dev ~/.codex/config.toml

# Переключить на производство
cp ~/.codex/config.toml.prod ~/.codex/config.toml
```

## Функции специфичные для Windsurf

Windsurf включает дополнительные опции конфигурации:

```toml theme={null}
model_provider = "megallm"
model = "gpt-5"

[model_providers.megallm]
name = "OpenAI using Chat Completions"
base_url = "https://ai.megallm.io/v1"
env_key = "MEGALLM_API_KEY"
query_params = {}

[windsurf]
cascade_mode = true           # Включить функцию Cascade AI
multi_file_edit = true        # Разрешить редактирование нескольких файлов
context_awareness = "enhanced" # enhanced, standard, minimal

[tools]
web_search = true
file_browser = true
terminal = true
supercomplete = true          # Функция автодополнения Windsurf
```

## Проверка

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

```bash theme={null}
# Просмотр конфигурации
cat ~/.codex/config.toml

# Проверка синтаксиса TOML (если установлен toml-cli)
toml-check ~/.codex/config.toml

# Проверка разрешений файла
ls -la ~/.codex/config.toml
```

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

```bash theme={null}
# Проверить API с вашими учетными данными
curl -H "Authorization: Bearer $MEGALLM_API_KEY" \
     -H "Content-Type: application/json" \
     https://ai.megallm.io/v1/models

# Должен вернуть список доступных моделей
```

### Проверка Codex/Windsurf

```bash theme={null}
# Запустить Codex/Windsurf
codex  # или 'windsurf'

# Проверить версию
codex --version  # или 'windsurf --version'
```

## Устранение неполадок

<AccordionGroup>
  <Accordion title="Файл конфигурации не найден">
    **Проверьте, существует ли каталог:**

    ```bash theme={null}
    ls -la ~/.codex/
    ```

    **Создайте, если отсутствует:**

    ```bash theme={null}
    mkdir -p ~/.codex
    # Затем создайте config.toml
    ```

    **Проверьте путь к файлу:**

    ```bash theme={null}
    # Должно быть точно:
    ~/.codex/config.toml
    # Не:
    ~/.config/codex/config.toml  # <Icon icon="xmark" /> Неправильное расположение
    ```
  </Accordion>

  <Accordion title="API ключ не работает">
    **Проверьте, установлена ли переменная окружения:**

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

    Если пусто:

    ```bash theme={null}
    # Добавить в конфигурацию оболочки
    echo 'export MEGALLM_API_KEY="your-key"' >> ~/.bashrc
    source ~/.bashrc
    ```

    **Проверьте формат ключа:**

    * Должен начинаться с `sk-mega-`
    * Не менее 20 символов
    * Без лишних пробелов или кавычек

    **Проверьте ключ:**

    ```bash theme={null}
    curl -H "Authorization: Bearer $MEGALLM_API_KEY" \
         https://ai.megallm.io/v1/models
    ```
  </Accordion>

  <Accordion title="Используется неправильный провайдер модели">
    **Проверьте файл конфигурации:**

    ```bash theme={null}
    cat ~/.codex/config.toml | grep model_provider
    # Должно показать: model_provider = "megallm"
    ```

    **Проверьте base\_url:**

    ```bash theme={null}
    cat ~/.codex/config.toml | grep base_url
    # Должно показать: base_url = "https://ai.megallm.io/v1"
    ```

    **Убедитесь в отсутствии опечаток:**

    ```toml theme={null}
    model_provider = "megallm"  # <Icon icon="check" /> Правильно
    # model_provider = "megalm"  # <Icon icon="xmark" /> Неправильно (опечатка)
    # model_provider = "openai"  # <Icon icon="xmark" /> Неправильно (другой провайдер)
    ```
  </Accordion>

  <Accordion title="Ошибки синтаксиса TOML">
    **Проверьте синтаксис:**

    ```bash theme={null}
    # Если у вас установлен toml-cli
    toml-check ~/.codex/config.toml

    # Или используйте Python
    python3 -c "import tomli; tomli.load(open('~/.codex/config.toml', 'rb'))"
    ```

    **Частые ошибки TOML:**

    ```toml theme={null}
    # <Icon icon="xmark" /> Неправильно - отсутствуют кавычки
    model_provider = megallm

    # <Icon icon="check" /> Правильно
    model_provider = "megallm"

    # <Icon icon="xmark" /> Неправильно - неверный синтаксис секции
    model_providers.megallm
    base_url = "..."

    # <Icon icon="check" /> Правильно
    [model_providers.megallm]
    base_url = "..."
    ```
  </Accordion>

  <Accordion title="Codex/Windsurf не обнаруживает конфигурацию">
    **П��резапустите Codex/Windsurf:**

    ```bash theme={null}
    # Закрыть все экземпляры
    pkill codex  # или 'pkill windsurf'

    # Запустить заново
    codex  # или 'windsurf'
    ```

    **Проверьте наличие нескольких файлов конфигурации:**

    ```bash theme={null}
    find ~ -name "config.toml" -path "*/.codex/*"
    # Должен показать только один файл
    ```

    **Проверьте разрешения:**

    ```bash theme={null}
    chmod 644 ~/.codex/config.toml
    ```
  </Accordion>
</AccordionGroup>

## Почему только системный уровень?

Codex и Windsurf не поддерживают конфигурацию уровня проекта, потому что:

1. **Единственный экземпляр** - Codex/Windsurf запускается как единственный экземпляр для всех проектов
2. **Глобальные настройки** - Настройки инструментов применяются системно
3. **Упрощенное управление** - Одна конфигурация для управления

**Обходной путь для ключей конкретных проектов:**

Используйте переменные окружения в вашем проекте:

```bash theme={null}
# В каталоге проекта
cat > .env << 'EOF'
MEGALLM_API_KEY=project-specific-key
EOF

# Загрузить перед запуском Codex
source .env && codex
```

Или создайте псевдонимы оболочки:

```bash theme={null}
# В ~/.bashrc или ~/.zshrc
alias codex-project-a='MEGALLM_API_KEY="key-for-project-a" codex'
alias codex-project-b='MEGALLM_API_KEY="key-for-project-b" codex'
```

## Лучшие практики

<CardGroup cols={2}>
  <Card title="Резервная конфигурация" icon="floppy-disk">
    Храните резервную копию `config.toml` перед внесением изменений
  </Card>

  <Card title="Используйте переменные окружения" icon="key">
    Храните API ключи в переменных окружения, а не в файле конфигурации
  </Card>

  <Card title="Контроль версий" icon="code-branch">
    Вы можете коммитить `config.toml`, если используется env\_key (без жестко закодированных ключей)
  </Card>

  <Card title="Регулярные обновления" icon="rotate">
    Поддерживайте Codex/Windsurf обновленными для последних функций
  </Card>
</CardGroup>

## Сравнение: Codex vs Windsurf

| Функция                          | Codex                 | Windsurf              |
| -------------------------------- | --------------------- | --------------------- |
| Базовая конфигурация             | <Icon icon="check" /> | <Icon icon="check" /> |
| Поддержка MegaLLM                | <Icon icon="check" /> | <Icon icon="check" /> |
| Расположение конфигурации        | `~/.codex/`           | `~/.codex/`           |
| Cascade AI                       | <Icon icon="xmark" /> | <Icon icon="check" /> |
| Supercomplete                    | <Icon icon="xmark" /> | <Icon icon="check" /> |
| Редактирование нескольких файлов | Базовое               | Расширенное           |

<Info>
  И Codex, и Windsurf используют одинаковое расположение и формат файла конфигурации.
</Info>

## Следующие шаги

<CardGroup cols={2}>
  <Card title="Конфигурация Claude Code" icon="robot" href="/ru/cli/claude-config">
    Настроить Claude Code
  </Card>

  <Card title="Конфигурация OpenCode" icon="brackets-curly" href="/ru/cli/opencode-config">
    Настроить OpenCode
  </Card>

  <Card title="Примеры" icon="code-branch" href="/ru/cli/examples">
    Просмотр практических примеров
  </Card>

  <Card title="Конфигурация всех агентов" icon="window" href="/ru/agents/overview">
    Настройка всех CLI и GUI агентов
  </Card>

  <Card title="Каталог моделей" icon="layer-group" href="/ru/home/models">
    Просмотр доступных моделей
  </Card>
</CardGroup>