Skip to main content

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

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

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

Для локального зашифрованного хранилища нужен ключ:
VELES_SECRETS_MASTER_KEY должен быть в окружении процесса сервера Велеса. Интерфейс Велеса не должен получать этот ключ.

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

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

​
SecretRef

SecretRef говорит Велесу, откуда брать секрет:
  • local — зашифрованное локальное хранилище Велеса;
  • env — переменная окружения процесса сервера;
  • file — файл на машине сервера;
  • exec — команда, которая возвращает секрет.
Для local используется объект, а не строковая подстановка:
Короткая строка вида "${NAME}" означает только ссылку на переменную окружения и не подходит для локальных секретов Велеса. Интерфейс Велеса в первую очередь управляет local: пользователь вводит значение один раз, Велес шифрует его и дальше возвращает только замаскированный статус. Пароль входа в Nerve тоже хранится на стороне Велеса, но не показывается как обычная цель в каталоге секретов. Велес записывает только scrypt-хэш пароля во внутренний ключ зашифрованного хранилища. Nerve при входе отправляет пароль в auth.login, получает gateway.token только в серверный процесс и не сохраняет его в браузере. Если это зашифрованное хранилище нельзя прочитать, Велес не считает пароль отсутствующим и не включает вход через gateway.token. Сначала восстановите ключ шифрования или доступ к хранилищу секретов.

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

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

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

Навык может объявить нужный секрет окружения в SKILL.md:
Тогда Велес создаст цель вроде skills.github.env.GH_TOKEN. Если значение сохранить в панели секретов, Велес будет подставлять GH_TOKEN только на время выполнения ответа. Значение не попадает в инструкцию модели и не записывается в config.json. requires.env делает переменную обязательной: без неё навык считается недоступным. Для опциональных API-ключей используйте отдельный список секретов:
Такой ключ появится в панели секретов и будет подставлен при наличии, но отсутствие значения не выключит навык. Например, встроенный навык fda-database объявляет опциональный OPENFDA_API_KEY как skills.fda-database.env.OPENFDA_API_KEY: ключ повышает дневной лимит openFDA, но без него навык всё равно работает. Навык google-workspace хранит более крупные значения: файл клиента Google, токен и временное состояние авторизации. Они тоже записываются в зашифрованное локальное хранилище, но как JSON-значения с ключами skills.google-workspace.google_client_secret_json, skills.google-workspace.google_token_json и skills.google-workspace.google_oauth_pending_json.

​
OpenAI Codex OAuth

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

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

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