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

# Провайдеры и модели

> Как Велес выбирает провайдера модели, настраивает ключи API, OAuth, локальные модели и список моделей в интерфейсе.

# Провайдеры и модели

Велес может работать с разными провайдерами моделей. Модель задаётся в `agents.defaults.model`, а провайдер выбирается явно через `agents.defaults.provider` или автоматически по имени модели и настройкам.

Это значение используется как общий дефолт. У отдельной [личности](/basics/personalities_ru) может быть собственная модель в `personality.json`, а переключение модели в интерфейсе остаётся переопределением для текущей сессии.

## Поддерживаемые типы

| Тип              | Примеры                                                | Когда использовать                         |
| ---------------- | ------------------------------------------------------ | ------------------------------------------ |
| API-провайдеры   | `openai`, `anthropic`, `deepseek`, `minimax`, `gemini` | Прямой доступ к конкретному провайдеру     |
| Провайдеры-шлюзы | `openrouter`, `aihubmix`                               | Один ключ для многих моделей               |
| Локальные        | `ollama`, `vllm`, `custom`                             | Модель на своей машине или сервере         |
| OAuth            | `openai_codex`, `github_copilot`                       | Вход через аккаунт, без API-ключа в config |

## Автовыбор провайдера

По умолчанию:

```json theme={null}
{
  "agents": {
    "defaults": {
      "provider": "auto"
    }
  }
}
```

Велес смотрит на префикс модели, ключевые слова и заполненные provider-блоки. Явный префикс выигрывает: например `openrouter/...` выбирает OpenRouter, а `openai-codex/...` выбирает Codex.

Когда в переключателе моделей есть записи с разными префиксами, Велес выбирает поставщика для каждого запроса отдельно. Префикс нужен только для маршрутизации и не отправляется внутрь выбранного поставщика: `custom/minimax-m2.7` уйдет в собственный совместимый адрес как `minimax-m2.7`, а `openrouter/minimax/minimax-m3` уйдет в OpenRouter как `minimax/minimax-m3`.

Если хотите убрать неоднозначность, задайте провайдера явно:

```json theme={null}
{
  "agents": {
    "defaults": {
      "provider": "ollama",
      "model": "llama3.2"
    }
  }
}
```

## API-провайдер

```json theme={null}
{
  "providers": {
    "anthropic": {
      "apiKey": "sk-ant-..."
    }
  },
  "agents": {
    "defaults": {
      "model": "anthropic/claude-sonnet-4-6"
    }
  }
}
```

Некоторые провайдеры требуют `apiBase`, если вы используете региональный адрес API или совместимый шлюз.

## OpenRouter

OpenRouter удобен как универсальный шлюз:

```json theme={null}
{
  "providers": {
    "openrouter": {
      "apiKey": "sk-or-..."
    }
  },
  "agents": {
    "defaults": {
      "model": "openrouter/openai/gpt-5.4"
    }
  }
}
```

## Собственный OpenAI-совместимый адрес API

Используйте `custom`, если у вас свой OpenAI-совместимый адрес API.

```json theme={null}
{
  "providers": {
    "custom": {
      "apiKey": "no-key",
      "apiBase": "https://api.example.com/v1"
    }
  },
  "agents": {
    "defaults": {
      "provider": "custom",
      "model": "my-model"
    }
  }
}
```

Для локального адреса API без ключа задайте любое непустое значение `apiKey`, например `no-key`.

## Ollama

```bash theme={null}
ollama run llama3.2
```

```json theme={null}
{
  "providers": {
    "ollama": {
      "apiBase": "http://localhost:11434"
    }
  },
  "agents": {
    "defaults": {
      "provider": "ollama",
      "model": "llama3.2"
    }
  }
}
```

## vLLM

```bash theme={null}
vllm serve meta-llama/Llama-3.1-8B-Instruct --port 8000
```

```json theme={null}
{
  "providers": {
    "vllm": {
      "apiKey": "dummy",
      "apiBase": "http://localhost:8000/v1"
    }
  },
  "agents": {
    "defaults": {
      "provider": "vllm",
      "model": "meta-llama/Llama-3.1-8B-Instruct"
    }
  }
}
```

## OpenAI Codex OAuth

Codex использует OAuth. Обычный `providers.openaiCodex.apiKey` не нужен.

```json theme={null}
{
  "providers": {
    "openaiCodex": {}
  }
}
```

Этот пустой блок только представляет поставщика в конфигурации. Действительное состояние подключения определяется зашифрованной записью OAuth; токены в `config.json` не сохраняются.

```bash theme={null}
veles provider login openai-codex
```

```json theme={null}
{
  "agents": {
    "defaults": {
      "model": "openai-codex/gpt-5.1-codex"
    }
  }
}
```

Если настроен `VELES_SECRETS_MASTER_KEY`, OAuth-токены сохраняются в зашифрованном хранилище профилей.

## Показатели расхода поставщиков

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

Nerve получает единый список через `providers.usage` и не содержит отдельных правил для OpenRouter или Codex. Поэтому новый поставщик с таким обработчиком появляется в подробной панели и списке показателей значка без изменений интерфейса. Поставщики без обработчика или без подключённых учётных данных в список не входят. При временной ошибке сохраняется последнее успешно полученное значение.

## GitHub Copilot OAuth

```bash theme={null}
veles provider login github-copilot
```

```json theme={null}
{
  "agents": {
    "defaults": {
      "model": "github-copilot/gpt-4.1"
    }
  }
}
```

## Список моделей в интерфейсе Велеса

Интерфейс Велеса показывает каталог моделей из `agents.defaults.models` и модель по умолчанию.

```json theme={null}
{
  "agents": {
    "defaults": {
      "model": "openrouter/openai/gpt-5.4",
      "models": [
        {
          "id": "openrouter/openai/gpt-5.4",
          "label": "GPT 5.4",
          "modalities": ["text", "image"],
          "reasoningEfforts": ["off", "low", "medium", "high", "xhigh"]
        },
        { "id": "openrouter/anthropic/claude-sonnet-4-6", "label": "Claude Sonnet", "modalities": ["text"] },
        "openrouter/google/gemini-2.5-pro"
      ]
    }
  }
}
```

Можно использовать строки, объекты `{ "id": "...", "label": "..." }` или словарь, где ключ — идентификатор модели, а значение — подпись. Для объектов можно указать `modalities`: запись без этого поля считается текстовой. Если пользователь прикрепит изображение, Велес передаст данные изображения только модели с `image` или `vision` в `modalities`; для текстовой или неописанной модели в запросе останется только текстовое описание вложения.

Поле `reasoningEfforts` ограничивает переключатель рассуждения конкретной модели. Nerve автоматически читает `reasoning.supported_efforts` и признак обязательного рассуждения из открытого каталога OpenRouter. Записи `openrouter/openai/<модель>` и `openai-codex/<модель>` используют в каталоге одну модель `openai/<модель>`, поэтому для них не нужны отдельные встроенные списки. Явный список имеет приоритет над автоматическим определением; используйте его, если поставщик ещё не публикует возможности модели или нужен более узкий набор.

Отсутствующее поле `supported_efforts` не означает поддержку всех уровней. В этом случае ручная настройка недоступна, а Nerve использует режим `auto`. Явное значение `null`, напротив, означает поддержку всех уровней шлюза. При переключении модели несовместимый уровень заменяется значением модели по умолчанию или режимом `auto` в одном обновлении с самой моделью. Если `default_effort` отсутствует или содержит неизвестное значение, Nerve не задаёт уровень по умолчанию.

## Практические советы

* Для интерфейса Велеса заранее задавайте `models`, чтобы пользователь не вводил идентификатор вручную.
* Для моделей, которые должны видеть изображения, явно добавляйте `modalities: ["text", "image"]`.
* Если автоматическое определение уровней рассуждения не подходит, задавайте для модели точный список `reasoningEfforts`.
* Для локальных моделей задавайте `provider` явно.
* Для провайдеров-шлюзов используйте префикс в `model`, чтобы не было неоднозначности.
* Не храните новые ключи plaintext в `config.json`; используйте [секреты](/basics/secrets_ru).