Конфигурация

SOBA конфигурируется через три источника с чётким приоритетом: CLI-флаги > переменные окружения > config.json

значения по умолчанию. Этот гайд объясняет все доступные опции и их взаимодействие.

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

Файл конфигурации находится в ~/.soba/config.json. При первом запуске SOBA создаёт его автоматически, либо его можно создать вручную. Пример полного файла:

{
  "baseUrl": "https://api.deepseek.com",
  "apiKey": "YOUR_API_KEY",
  "model": "deepseek/deepseek-v4-flash",
  "maxOutputTokens": 8192,
  "maxCompletionTokens": 0,
  "reasoning": { "mode": "provider_default" },
  "contextWindow": 65536,
  "temperature": 0.7,
  "maxAgentIterations": 0,
  "maxStalledIterations": 4,
  "maxRunMinutes": 0,
  "bashMaxTimeoutSeconds": 300,
  "sessionDir": "~/.soba/sessions",
  "lang": "ru",
  "theme": "graphite",
  "compaction": {
    "auto": true,
    "compactOnTurnComplete": true,
    "compactOnMilestone": true,
    "minTokensForAutoCompact": 32000,
    "minReclaimableTokens": 12000,
    "minSavingsRatio": 0.25,
    "keepRecentTokens": 20000,
    "safetyReserveTokens": 8192,
    "autoCompactThresholdRatio": 0.8,
    "timeoutMs": 15000
  },
  "registry": {
    "activeProvider": "deepseek",
    "activeModelId": "deepseek-v4-flash",
    "customProviders": []
  }
}

Минимальная конфигурация (только обязательные поля):

{
  "apiKey": "YOUR_API_KEY",
  "model": "deepseek/deepseek-v4-flash"
}

2. Полный список параметров

2.1. Параметры провайдера

2.2. Параметры ответов модели

2.3. Параметры безопасности выполнения

2.4. Параметры сессий

2.5. Параметры интерфейса

2.6. Compaction (сжатие контекста)

См. раздел 6.

2.7. Registry (провайдеры и модели)

См. раздел 5.

3. Переменные окружения

Все параметры конфигурации можно задать через переменные окружения. Они имеют более высокий приоритет, чем config.json.

4. CLI-флаги

Высший приоритет. Переопределяют и переменные окружения, и config.json.

4.1. Режимы запуска

4.2. Провайдер и модель

4.3. Параметры ответов и лимитов

4.4. Управление и отладка

4.5. Информация

5. Конфигурация провайдеров

SOBA v0.6.x использует систему реестра провайдеров (registry). Подробнее о провайдерах — в гайде по провайдерам.

5.1. Встроенные провайдеры

SOBA поставляется с 5 встроенными провайдерами:

Модели для каждого провайдера обнаруживаются динамически через GET /models и кэшируются в памяти текущего процесса. Селектор модели в TUI (F2 или /model) запускает refresh встроенных провайдеров.

Discovery также читает context/output limits и reasoning capabilities. Приоритет лимитов: явная настройка пользователя → runtime → active route → model metadata → точный встроенный профиль → консервативный fallback. SOBA не угадывает capabilities по имени модели; assumed-значения отмечаются ~ и предупреждением при выборе.

5.2. Кастомные провайдеры

Добавление своего провайдера:

soba provider add my-llm \
  --base-url https://api.myllm.com/v1 \
  --api-key-env MY_LLM_KEY \
  --model my-code-model="My Code Model",128000,8192

Кастомные провайдеры сохраняются в registry.customProviders внутри ~/.soba/config.json.

Особенности wire-формата конкретной модели задаются в полном JSON-описании провайдера, загружаемом через soba provider add <id> --from-file <path>. Например, "compatibility": ["single_system_message"] заставляет SOBA отправлять одно начальное системное сообщение для chat templates, которые отклоняют несколько таких сообщений. Полная схема и список features приведены в разделе метаданных совместимости модели.

5.3. Управление через CLI

# Просмотр всех провайдеров и моделей
soba provider list

# Добавить кастомный провайдер
soba provider add <id> --base-url <url> --model <spec> [--api-key-env <VAR>]

# Показать определение провайдера
soba provider show <id>

# Удалить кастомный провайдер
soba provider remove <id>

# Выбрать активного провайдера (использует его default model)
soba provider use <provider-id>

6. Compaction конфигурация

Compaction управляется через секцию compaction в ~/.soba/config.json.

Формула hard limit:

hardLimit = contextWindow - maxOutputTokens - safetyReserveTokens

Когда эффективных токенов больше чем hardLimit, выполняется блокирующий compaction. Это нельзя отключить через auto: false.

Подробнее: Compaction и Context Capsules.

7. Приоритет и переопределение

CLI-флаги (высший приоритет)
    ↓ переопределяет
Переменные окружения
    ↓ переопределяет
config.json
    ↓ переопределяет
Значения по умолчанию (низший приоритет)

Пример: Если в config.json указано "theme": "graphite", а в переменной окружения SOBA_THEME=forest и передан CLI-флаг --theme paper — будет использоваться paper.

Особые правила

• Reasoning: request/session override → CLI → env → config → provider default. /reasoning и F4 меняют следующий model request без перезапуска.

• Requested и effective reasoning хранятся отдельно. Неподдерживаемый режим даёт видимый fallback к provider default без скрытого clamp.

• maxOutputTokens и contextWindow: извлекаются из активной модели и метаданных provider/runtime/route. CLI-флаг --max-output-tokens, --context-window или явные model limits переопределяют discovery для локальных прокси и неполных каталогов.

• auto в compaction: SOBA_AUTO_COMPACT=false или --no-auto-compact переопределяет compaction.auto.

• Отключение auto-compaction выключает только мягкие trigger. Hard limit и восстановление после provider overflow остаются обязательными.

• Trigger после turn и milestone откладывается: SOBA показывает прогресс и ожидает compact непосредственно перед следующим model call.

• Строковые и числовые значения: 0 для maxAgentIterations и maxRunMinutes означает «без лимита» (unlimited). Для maxCompletionTokens — «без явного лимита» (используется дефолт провайдера).

8. Валидация конфигурации

SOBA выполняет валидацию при старте:

• API-ключ обязателен — если не указан, будет ошибка.
• model обязателен — если не указан, агент не сможет делать запросы.
• Compaction инварианты:
  • contextWindow > 0
  • maxOutputTokens > 0
  • safetyReserveTokens >= 0
  • maxOutputTokens + safetyReserveTokens < contextWindow
  • keepRecentTokens < contextWindow - maxOutputTokens - safetyReserveTokens

При нарушении инвариантов compaction отключается с предупреждением в лог.

⚠️  Compaction disabled: config validation failed:
    keepRecentTokens (50000) must be < hard limit (47360)