Skip to main content

​
Секреты и токены

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

​
Главный ключ

Для локального зашифрованного хранилища нужен ключ: 
uv run veles secrets generate-key
$env:VELES_SECRETS_MASTER_KEY="PASTE_GENERATED_KEY"
uv run veles gateway
VELES_SECRETS_MASTER_KEY должен быть в окружении процесса сервера Велеса. Интерфейс Велеса не должен получать этот ключ.

​
Где лежат локальные секреты

Зашифрованное локальное хранилище пишет файлы в активный каталог служебных данных:
  • <data_dir>/secrets/values.enc.json — обычные ключи API и секреты окружения навыков;
  • <data_dir>/secrets/auth-profiles.enc.json — OAuth-профили, например OpenAI Codex.
Файлы содержат зашифрованную оболочку AES-GCM (version, alg, nonce, ciphertext, timestamps). Значения секретов не лежат там открытым текстом.

​
SecretRef

SecretRef говорит Велесу, откуда брать секрет:
  • local — зашифрованное локальное хранилище Велеса;
  • env — переменная окружения процесса сервера;
  • file — файл на машине сервера;
  • exec — команда, которая возвращает секрет.
Интерфейс Велеса в первую очередь управляет local: пользователь вводит значение один раз, Велес шифрует его и дальше возвращает только замаскированный статус.

​
Как интерфейс показывает секреты

В интерфейсе Велеса откройте «Рабочая область» → «Секреты». Интерфейс получает список целей так:
  1. GET /api/secrets;
  2. внутренний вызов secrets.catalog;
  3. Велес строит каталог из провайдеров, инструментов, каналов, MCP-серверов и метаданных навыков.
Если строка показывает MISSING или EMPTY, это не значит, что секрет находится в интерфейсе. Это только замаскированная цель: Велес знает, что такой секрет может понадобиться, но значение ещё не настроено. Поле поиска в панели Секреты фильтрует уже загруженный список на стороне Nerve. Оно не делает дополнительных запросов к gateway и ищет по названию секрета, target id, пути конфигурации и источнику.

​
Секреты навыков

Навык может объявить нужный секрет окружения в SKILL.md: 
metadata: {"veles":{"requires":{"env":["GH_TOKEN"]}}}
Тогда Велес создаст цель вроде skills.github.env.GH_TOKEN. Если значение сохранить в панели секретов, Велес будет подставлять GH_TOKEN только на время выполнения ответа. Значение не попадает в инструкцию модели и не записывается в config.json. requires.env делает переменную обязательной: без неё навык считается недоступным. Для опциональных API-ключей используйте отдельный список секретов: 
metadata: {"veles":{"secrets":{"env":["NCBI_API_KEY"]}}}
Такой ключ появится в панели секретов и будет подставлен при наличии, но отсутствие значения не выключит навык. Например, встроенный навык fda-database объявляет опциональный OPENFDA_API_KEY как skills.fda-database.env.OPENFDA_API_KEY: ключ повышает дневной лимит openFDA, но без него навык всё равно работает.

​
OpenAI Codex OAuth

OpenAI Codex использует OAuth, а не ключ API. Его токены хранятся в зашифрованном хранилище профилей: 
<data_dir>/secrets/auth-profiles.enc.json
Подключить или отключить Codex можно через интерфейс Велеса: «Рабочая область» → «Секреты». Браузер получает только ссылку и статус OAuth; токены доступа и обновления остаются внутри Велеса.

​
Что важно помнить

  • config.json не должен хранить новые секреты открытым текстом.
  • Интерфейс Велеса никогда не показывает сохранённое значение секрета.
  • Без VELES_SECRETS_MASTER_KEY чтение ссылок env, file и exec может работать, но локальная запись зашифрованных секретов и OAuth-хранилище будут недоступны.
  • Для постоянного развёртывания нужно сохранять каталог .veles и передавать главный ключ через менеджер секретов окружения.