Полное руководство по настройке моделей в OpenClaw: от основ до продвинутых приёмов (2026)

Кратко

OpenClaw установить легко — сложнее правильно настроить. Многие запускают openclaw onboard и считают дело сделанным, а потом теряются при переключении моделей, настройке fallback или мультиагентной конфигурации. В этом руководстве мы разбираем структуру каталога ~/.openclaw/, подробно рассматриваем каждый параметр моделей и пошагово показываем мультимодельную ротацию, автодеградацию и контроль бюджета. Все примеры конфигурации можно использовать как есть.

Содержание

• Начинаем с onboard: инициализация конфигурации
• Структура каталога ~/.openclaw/
• Параметры конфигурации модели: разбор по пунктам
• Полные примеры: от одной модели до нескольких
• Продвинутая настройка: мультимодельная ротация и Fallback
• Оптимальные конфигурации для разных сценариев
• Диагностика типичных ошибок конфигурации
• Часто задаваемые вопросы (FAQ)
• Итоги
• Полезные ссылки

Начинаем с onboard: инициализация конфигурации

После установки OpenClaw первое, что нужно сделать — запустить команду onboard:

openclaw onboard

Пошаговый мастер задаст четыре вопроса:

Шаг 1: Выбор провайдера AI

? Select your AI provider:
  > OpenAI (официальный)
    Anthropic (официальный)
    Google (официальный)
    Custom (сторонний / агрегатор)   ← выберите этот пункт для Ofox и подобных платформ

При выборе Custom нужно будет ввести base_url. Если используете агрегатор Ofox, введите:

https://api.ofox.ai/v1

Шаг 2: Ввод API Key

? Enter your API Key:
sk-xxxxxxxxxxxxxxxx

При использовании агрегатора достаточно одного ключа — не нужно отдельно регистрироваться в OpenAI, Anthropic и Google.

Шаг 3: Выбор модели по умолчанию

? Select default model:
  > claude-sonnet-4-6
    gpt-4o
    gemini-3-pro
    deepseek-v3.2
    (type to search...)

Для повседневного использования рекомендуем claude-sonnet-4-6 или gpt-4o — лучшее соотношение цена/качество.

Шаг 4: Настройка Search Provider

? Select search provider:
  > Tavily (рекомендуется, бесплатный баланс при регистрации)
    Google Search
    Bing Search
    Skip

Если веб-поиск не нужен — выберите Skip, потом можно добавить.

После завершения onboard OpenClaw создаёт файлы конфигурации в каталоге ~/.openclaw/. Большинство пользователей начинают работу на этом этапе — но это лишь отправная точка.

Структура каталога ~/.openclaw/

После завершения onboard каталог ~/.openclaw/ выглядит примерно так:

~/.openclaw/
├── config.yaml          # Глобальная конфигурация (основной файл)
├── models.yaml          # Определения моделей (все доступные модели)
├── agents/              # Конфигурация ролей Agent
│   └── default.yaml     # Agent по умолчанию
├── memory/              # Хранилище памяти
│   ├── core.md          # Основная память
│   └── conversations/   # История диалогов
├── plugins/             # Конфигурация плагинов
├── .env                 # Переменные окружения (опционально)
└── logs/                # Логи работы

Три ключевых файла: config.yaml (глобальное поведение), models.yaml (определения моделей), agents/default.yaml (роль Agent). Разберём каждый.

config.yaml: глобальная конфигурация

Главный конфигурационный файл OpenClaw, управляющий общим поведением:

# ~/.openclaw/config.yaml

# Модель по умолчанию
default_model: claude-sonnet-4-6

# Стратегия маршрутизации моделей
model_routing:
  primary: claude-sonnet-4-6        # Основная модель
  fallback: gpt-4o                   # Резервная при сбое основной
  economy: deepseek-v3.2             # Экономичная для простых задач

# Настройка поиска
search:
  provider: tavily
  api_key: tvly-xxxxxxxx

# Контроль бюджета
budget:
  daily_limit: 500000       # Дневной лимит токенов
  monthly_limit: 10000000   # Месячный лимит токенов
  warning_threshold: 0.8    # Предупреждение при 80%

# Логирование
logging:
  level: info               # debug / info / warn / error
  file: ~/.openclaw/logs/openclaw.log

# Безопасность
security:
  allowed_commands:          # Белый список разрешённых системных команд
    - git
    - npm
    - python3
    - curl
  blocked_paths:             # Запрещённые пути
    - /etc/
    - /var/

models.yaml: определения моделей

Файл с определениями всех доступных моделей. Каждая модель — отдельная запись:

# ~/.openclaw/models.yaml

models:
  - name: claude-sonnet-4-6
    provider: anthropic
    model: claude-sonnet-4-6
    base_url: https://api.ofox.ai/v1
    api_key: ${OPENCLAW_API_KEY}    # Ссылка на переменную окружения
    max_tokens: 8192
    temperature: 0.7
    timeout: 60

  - name: claude-opus-4-6
    provider: anthropic
    model: claude-opus-4-6
    base_url: https://api.ofox.ai/v1
    api_key: ${OPENCLAW_API_KEY}
    max_tokens: 16384
    temperature: 0.3
    timeout: 120

  - name: gpt-4o
    provider: openai
    model: gpt-4o
    base_url: https://api.ofox.ai/v1
    api_key: ${OPENCLAW_API_KEY}
    max_tokens: 4096
    temperature: 0.7
    timeout: 45

  - name: deepseek-v3.2
    provider: deepseek
    model: deepseek-chat
    base_url: https://api.ofox.ai/v1
    api_key: ${OPENCLAW_API_KEY}
    max_tokens: 8192
    temperature: 0.7
    timeout: 30

Обратите внимание: api_key использует синтаксис ${OPENCLAW_API_KEY} для ссылки на переменную окружения — это безопаснее, чем хранить ключ прямо в файле.

Параметры конфигурации модели: разбор по пунктам

Каждая запись модели в models.yaml поддерживает следующие параметры:

Рекомендации по ключевым параметрам

temperature

Этот параметр существенно влияет на качество вывода; оптимальные значения зависят от сценария:

max_tokens

Не ставьте слишком маленькое значение, иначе ответ модели обрежется на полуслове. Рекомендации по моделям:

timeout

Устанавливайте в зависимости от скорости модели:

• Лёгкие модели (GPT-4o-mini, Gemini Flash): 30 секунд
• Основные модели (Sonnet, GPT-4o): 60 секунд
• Флагманские модели (Opus, GPT-5.4 Thinking): 120 секунд
• Генерация длинных текстов: 300 секунд

Полные примеры: от одной модели до нескольких

Минимальная конфигурация: одна модель

Для начала — простейшая конфигурация:

# ~/.openclaw/config.yaml
default_model: claude-sonnet-4-6

# ~/.openclaw/models.yaml
models:
  - name: claude-sonnet-4-6
    provider: anthropic
    model: claude-sonnet-4-6
    base_url: https://api.ofox.ai/v1
    api_key: sk-your-ofox-key-here
    temperature: 0.7

Менее 10 строк в двух файлах — и всё работает.

Продвинутая конфигурация: основная + резервная модель

В реальной работе рекомендуем настроить минимум две модели — основная иногда даёт сбои (ограничение скорости, таймаут), резервная не даст застрять:

# ~/.openclaw/config.yaml
default_model: claude-sonnet-4-6
model_routing:
  primary: claude-sonnet-4-6
  fallback: gpt-4o

# ~/.openclaw/models.yaml
models:
  - name: claude-sonnet-4-6
    provider: anthropic
    model: claude-sonnet-4-6
    base_url: https://api.ofox.ai/v1
    api_key: ${OPENCLAW_API_KEY}
    max_tokens: 8192
    temperature: 0.7
    timeout: 60
    max_retries: 2

  - name: gpt-4o
    provider: openai
    model: gpt-4o
    base_url: https://api.ofox.ai/v1
    api_key: ${OPENCLAW_API_KEY}
    max_tokens: 4096
    temperature: 0.7
    timeout: 45
    max_retries: 2

Полная конфигурация: три уровня моделей + контроль бюджета

Конфигурация, которую я использую сам — покрывает большинство сценариев:

# ~/.openclaw/config.yaml
default_model: claude-sonnet-4-6

model_routing:
  primary: claude-sonnet-4-6
  strong: claude-opus-4-6           # Автоматическое повышение для сложных задач
  economy: deepseek-v3.2            # Автоматическое понижение для простых задач
  fallback:
    - gpt-4o                        # Первый резерв
    - gemini-3-flash                # Второй резерв

auto_routing:
  enabled: true
  complexity_threshold:
    strong: 0.8                     # Сложность > 0.8 → strong-модель
    economy: 0.3                    # Сложность < 0.3 → economy-модель

budget:
  daily_limit: 500000
  monthly_limit: 10000000
  warning_threshold: 0.8
  on_exceed: downgrade              # При превышении — деградация до экономичной модели

search:
  provider: tavily
  api_key: ${TAVILY_API_KEY}

logging:
  level: info
  file: ~/.openclaw/logs/openclaw.log

# ~/.openclaw/models.yaml
models:
  - name: claude-sonnet-4-6
    provider: anthropic
    model: claude-sonnet-4-6
    base_url: https://api.ofox.ai/v1
    api_key: ${OPENCLAW_API_KEY}
    max_tokens: 8192
    temperature: 0.7
    timeout: 60
    max_retries: 2
    streaming: true

  - name: claude-opus-4-6
    provider: anthropic
    model: claude-opus-4-6
    base_url: https://api.ofox.ai/v1
    api_key: ${OPENCLAW_API_KEY}
    max_tokens: 16384
    temperature: 0.3
    timeout: 120
    max_retries: 1
    streaming: true

  - name: gpt-4o
    provider: openai
    model: gpt-4o
    base_url: https://api.ofox.ai/v1
    api_key: ${OPENCLAW_API_KEY}
    max_tokens: 4096
    temperature: 0.7
    timeout: 45
    max_retries: 2
    streaming: true

  - name: deepseek-v3.2
    provider: deepseek
    model: deepseek-chat
    base_url: https://api.ofox.ai/v1
    api_key: ${OPENCLAW_API_KEY}
    max_tokens: 8192
    temperature: 0.7
    timeout: 30
    max_retries: 3
    streaming: true

  - name: gemini-3-flash
    provider: google
    model: gemini-3.0-flash
    base_url: https://api.ofox.ai/v1
    api_key: ${OPENCLAW_API_KEY}
    max_tokens: 4096
    temperature: 0.7
    timeout: 20
    max_retries: 2
    streaming: true

Результат этой конфигурации: большинство запросов идут на Sonnet (лучшее соотношение цена/качество), сложные рассуждения или генерация кода автоматически переключаются на Opus, простые переводы и суммаризации — на DeepSeek для экономии, при сбое любой модели автоматический переход на GPT-4o или Gemini Flash.

Через агрегатор Ofox все пять моделей работают с одним API Key — не нужно регистрироваться на пяти платформах.

Продвинутая настройка: мультимодельная ротация и Fallback

Принцип работы цепочки Fallback

При сбое основной модели OpenClaw действует по следующему алгоритму:

1. Определяет тип ошибки (таймаут? ограничение скорости? модель недоступна?)
2. Если задано max_retries, сначала повторяет запрос к текущей модели
3. После исчерпания повторов переходит к следующей модели в списке fallback
4. Если все fallback-модели недоступны — возвращает ошибку и предлагает переключиться вручную через /model

# Детальная конфигурация fallback
model_routing:
  primary: claude-sonnet-4-6
  fallback:
    - model: gpt-4o
      on_errors: [timeout, rate_limit, server_error]
    - model: deepseek-v3.2
      on_errors: [timeout, rate_limit, server_error, model_unavailable]
    - model: gemini-3-flash
      on_errors: [all]       # Последний рубеж — принимает любую ошибку

Обработка ограничения скорости

Стратегия при получении ошибки 429 (Rate Limit):

rate_limit:
  strategy: exponential_backoff    # Экспоненциальная задержка
  initial_delay: 2                 # Первая пауза — 2 секунды
  max_delay: 30                    # Максимальная пауза — 30 секунд
  auto_fallback: true              # При исчерпании пауз — автопереключение модели

Индивидуальные модели для разных Agent

Разные Agent могут использовать разные модели. Создайте отдельные файлы в ~/.openclaw/agents/:

# ~/.openclaw/agents/coder.yaml
name: Coder
description: Специализированный помощник по коду
model: claude-opus-4-6              # Для кода — самая мощная модель
temperature: 0.2                     # Низкая случайность для генерации кода
max_tokens: 16384
system_prompt: |
  Ты опытный программист, специализирующийся на ревью кода, исправлении багов и проектировании архитектуры.
  При выводе кода придерживайся лучших практик и принципов читаемости.

# ~/.openclaw/agents/assistant.yaml
name: Assistant
description: Офисный помощник на каждый день
model: deepseek-v3.2               # Для повседневных задач — экономичная модель
temperature: 0.7
max_tokens: 4096
system_prompt: |
  Ты эффективный офисный ассистент, специализирующийся на управлении расписанием, обработке почты и поиске информации.
  Отвечай кратко и точно, при необходимости предлагай дальнейшие шаги.

# ~/.openclaw/agents/researcher.yaml
name: Researcher
description: Глубокие исследования и анализ
model: claude-sonnet-4-6            # Для исследований — основная модель
temperature: 0.5
max_tokens: 8192
system_prompt: |
  Ты профессиональный аналитик-исследователь, специализирующийся на глубоком анализе и написании отчётов.
  Структурируй выводы, подкрепляй тезисы данными, разделяй факты и предположения.

Преимущества такого подхода: Agent для кода использует самую мощную модель для гарантии качества, повседневный Agent — экономичную модель для контроля расходов. Каждый выполняет свою роль.

Оптимальные конфигурации для разных сценариев

Сценарий 1: Индивидуальный разработчик (ограниченный бюджет)

Цель: минимальные расходы, достаточная функциональность для ежедневных задач.

# config.yaml
default_model: deepseek-v3.2
model_routing:
  primary: deepseek-v3.2
  strong: claude-sonnet-4-6          # Мощная модель только для сложных задач
budget:
  daily_limit: 200000
  monthly_limit: 3000000
  on_exceed: pause                   # При превышении — полная остановка

Средние расходы в месяц: 30–80 юаней.

Сценарий 2: Fullstack-команда разработчиков

Цель: качество кода в приоритете, стоимость вторична.

# config.yaml
default_model: claude-sonnet-4-6
model_routing:
  primary: claude-sonnet-4-6
  strong: claude-opus-4-6
  economy: deepseek-v3.2
  fallback:
    - gpt-4o
    - gemini-3-flash
auto_routing:
  enabled: true
budget:
  daily_limit: 1000000
  monthly_limit: 20000000
  on_exceed: downgrade

Средние расходы в месяц: 200–500 юаней на человека.

Сценарий 3: Корпоративная поддержка / автоматизация 24/7

Цель: стабильность прежде всего, нельзя допустить остановку.

# config.yaml
default_model: gpt-4o
model_routing:
  primary: gpt-4o
  fallback:
    - claude-sonnet-4-6
    - deepseek-v3.2
    - gemini-3-flash
    - gpt-4o-mini                    # Последний рубеж

rate_limit:
  strategy: exponential_backoff
  auto_fallback: true

health_check:
  enabled: true
  interval: 300                      # Проверка доступности моделей каждые 5 минут
  auto_switch: true                  # Автопереключение при недоступности

Средние расходы в месяц: 500–2000 юаней (зависит от объёма запросов).

Сравнение трёх сценариев

Диагностика типичных ошибок конфигурации

Ошибка 1: invalid model: xxx

Причина: идентификатор модели не распознан API-провайдером.

Диагностика:

# Просмотр списка моделей текущего провайдера
openclaw models list

# Проверьте написание поля model в models.yaml
# Частые ошибки:
#   claude-sonnet → правильно: claude-sonnet-4-6
#   gpt-4 → правильно: gpt-4o
#   deepseek → правильно: deepseek-chat

Ошибка 2: authentication failed / invalid api key

Причина: API Key недействителен или не загрузился.

Диагностика:

# Проверьте, задана ли переменная окружения
echo $OPENCLAW_API_KEY

# Если используете .env, проверьте формат (без пробелов вокруг знака равенства)
cat ~/.openclaw/.env
# Правильно: OPENCLAW_API_KEY=sk-xxxxx
# Ошибка:    OPENCLAW_API_KEY = sk-xxxxx

# Прямая проверка работоспособности API Key
curl -s https://api.ofox.ai/v1/models \
  -H "Authorization: Bearer sk-your-key" | head -20

Ошибка 3: timeout — превышение времени ожидания

Причина: слишком короткий timeout или высокая задержка сети до API-эндпоинта.

Диагностика:

# Замер задержки до API-эндпоинта
curl -o /dev/null -s -w "time_total: %{time_total}s\n" \
  https://api.ofox.ai/v1/models \
  -H "Authorization: Bearer sk-your-key"

# Если задержка > 2 секунд:
# 1. Увеличьте значение timeout
# 2. Переключитесь на провайдера с узлами ускорения

Ошибка 4: Синтаксическая ошибка YAML

Самая коварная проблема. OpenClaw не всегда явно сообщает об ошибке разбора YAML — может просто игнорировать конфигурацию.

# Проверка синтаксиса конфигурации
openclaw config validate

# Типичные ошибки YAML:
# 1. Использование Tab вместо пробелов для отступов (нужны только пробелы)
# 2. Отсутствие пробела после двоеточия (name:value → name: value)
# 3. Спецсимволы в строке без кавычек (api_key: sk-xxx#123 → api_key: "sk-xxx#123")

Ошибка 5: Изменения конфигурации не вступают в силу

Причина: часть настроек требует перезапуска.

# После изменения models.yaml необходим перезапуск
openclaw restart

# Параметры config.yaml с поддержкой горячей перезагрузки (перезапуск не нужен):
#   - budget
#   - logging.level
#   - security.allowed_commands

# Проверка, какой файл конфигурации загружен
openclaw config show --source

Ошибка 6: Переменные окружения не переопределяют конфигурацию

Приоритет: аргументы командной строки > переменные окружения > файл .env > значения по умолчанию в config.yaml.

# Просмотр всех источников активной конфигурации
openclaw config show --verbose

# Если .env не работает, проверьте расположение файла:
# ~/.openclaw/.env      ← глобальный
# ./.env                ← на уровне проекта (текущий каталог)

Часто задаваемые вопросы (FAQ)

Где хранятся файлы конфигурации OpenClaw?

Все файлы конфигурации — в каталоге ~/.openclaw/. Основные: config.yaml (глобальная конфигурация) и models.yaml (определения моделей). При первом запуске openclaw onboard файлы создаются автоматически, но можно создать и отредактировать вручную.

Можно ли пропустить настройку onboard?

Да. Просто создайте config.yaml и models.yaml в каталоге ~/.openclaw/ и заполните параметры моделей. Но новичкам это не рекомендуется — мастер onboard проверяет подключение и помогает избежать типичных ошибок.

YAML или JSON — какой формат выбрать?

Рекомендуем YAML. YAML поддерживает комментарии (#), значительно проще читается. OpenClaw распознаёт формат автоматически — подходят и config.yaml, и config.json, но два файла одновременно использовать нельзя.

Можно ли использовать разные API Key для разных моделей?

Да. У каждой записи модели есть собственное поле api_key. Например, китайские модели — с ключом DeepSeek, зарубежные — с ключом Ofox:

models:
  - name: deepseek-v3.2
    api_key: ${DEEPSEEK_API_KEY}
    base_url: https://api.deepseek.com/v1
  - name: claude-sonnet-4-6
    api_key: ${OFOX_API_KEY}
    base_url: https://api.ofox.ai/v1

При использовании агрегатора одного ключа достаточно для всех моделей — управлять проще.

Как узнать, какая модель сейчас активна?

# Текущая активная модель
openclaw status

# Статистика использования моделей
openclaw usage --detail

# Журнал переключений моделей за последние 24 часа
openclaw logs --filter model_switch --since 24h

Что если настройка модели Agent конфликтует с глобальной?

Конфигурация Agent имеет более высокий приоритет. Если в agents/coder.yaml указано model: claude-opus-4-6, Agent Coder будет использовать Opus, даже если глобальный default_model — Sonnet.

Порядок приоритетов от высшего к низшему: аргументы командной строки → конфигурация Agent → глобальная конфигурация → значения по умолчанию.

Можно ли хранить конфигурацию в каталоге проекта?

Да. OpenClaw поддерживает конфигурацию на уровне проекта — создайте каталог .openclaw/ в корне проекта и поместите в него config.yaml и models.yaml. Конфигурация проекта переопределяет глобальную. Это удобно для командной работы: нечувствительные параметры (выбор модели, temperature и т.д.) фиксируются в репозитории, API Key передаётся через переменные окружения.

Как проверить правильность конфигурации?

# Проверка синтаксиса
openclaw config validate

# Тест подключения ко всем моделям
openclaw models test

# Тест конкретной модели
openclaw models test --model claude-sonnet-4-6

# Пробный диалог для проверки сквозной работы
openclaw chat "Привет, ответь OK"

Слишком много параметров — как не запутаться?

Два совета:

1. Команда openclaw config show в любой момент покажет полную активную конфигурацию
2. Храните конфигурационные файлы в системе контроля версий (не забудьте добавить .env с API Key в .gitignore)

Конфигурация OpenClaw — инкрементальная: начните с простейшей конфигурации с одной моделью, добавляйте параметры по мере необходимости. Не нужно настраивать всё сразу.

Итоги

Система конфигурации моделей OpenClaw состоит из трёх уровней:

1. Базовый: openclaw onboard создаёт начальную конфигурацию — одной модели достаточно для работы
2. Продвинутый: primary + fallback (две модели) для обеспечения стабильности
3. Экспертный: трёхуровневая маршрутизация + контроль бюджета + индивидуальные модели для каждого Agent — баланс качества, стоимости и надёжности

Ключевой принцип один: не отправляйте все задачи на самую дорогую модель. 80% повседневных задач Sonnet/GPT-4o решают с запасом — только действительно сложные задачи заслуживают Opus или GPT-5.4 Thinking. В сочетании с экономичными моделями для простых запросов среднемесячные расходы можно снизить более чем на 60%.

Если у вас ещё нет единого решения для управления API, попробуйте Ofox — один ключ для всех моделей, без хлопот с регистрацией и управлением на нескольких платформах. Стартовый баланс при регистрации — настройка конфигурации без затрат.

Полезные ссылки

• OpenClaw — руководство по конфигурации — полный справочник параметров
• OpenClaw — управление моделями — конфигурация и маршрутизация моделей
• OpenClaw — GitHub-репозиторий — исходный код и примеры конфигураций
• Ofox AI API — документация — подключение и список моделей
• Ofox — руководство по интеграции с OpenClaw — специальная инструкция
• OpenClaw: рекомендации по API и настройке моделей — полное руководство