> ## Documentation Index > Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt > Use this file to discover all available pages before exploring further. # SecretRefs хранилища секретов # SecretRef для Vault Встроенный плагин Vault позволяет OpenClaw разрешать `exec` SecretRef из HashiCorp Vault при запуске и перезагрузке Gateway. OpenClaw хранит ссылки Vault в конфигурации, сохраняет разрешённые значения в снимке секретов в памяти и не записывает разрешённые API-ключи обратно в `openclaw.json`. Используйте этот вариант, если вы уже используете Vault или хотите хранить ключи поставщиков моделей вне файлов конфигурации OpenClaw. О модели выполнения SecretRef см. [Управление секретами](/ru/gateway/secrets). ## Перед началом Вам потребуется: * OpenClaw с доступным встроенным плагином `vault` * доступный сервер Vault * аутентификация Vault, позволяющая получить клиентский токен с доступом на чтение путей секретов, которые должен разрешать OpenClaw * среда, запускающая Gateway, должна содержать `VAULT_ADDR` и либо `VAULT_TOKEN`, либо `OPENCLAW_VAULT_AUTH_METHOD=token_file` вместе с `VAULT_TOKEN_FILE`, либо настроенный вход через JWT/Kubernetes Средство разрешения взаимодействует с Vault по HTTP из Node. Для разрешения SecretRef Gateway не требуется CLI Vault. Включите встроенный плагин перед выполнением команд `openclaw vault`: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw plugins enable vault ``` ## Сохранение ключа поставщика в Vault По умолчанию OpenClaw использует KV v2, смонтированный в `secret`, как в примерах с сервером разработки Vault. Для рабочего сервера Vault перед созданием идентификаторов SecretRef задайте для `OPENCLAW_VAULT_KV_MOUNT` фактический путь монтирования KV. При стандартных настройках OpenClaw этот идентификатор SecretRef: ```text theme={"theme":{"light":"min-light","dark":"min-dark"}} providers/openrouter/apiKey ``` считывает следующее поле Vault: ```text theme={"theme":{"light":"min-light","dark":"min-dark"}} secret/data/providers/openrouter -> apiKey ``` Один из способов создать его с помощью CLI Vault: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} export OPENROUTER_API_KEY= vault kv put secret/providers/openrouter apiKey="$OPENROUTER_API_KEY" ``` Используйте для OpenClaw клиентский токен с ограниченной областью действия, а не корневой токен. Для стандартной структуры KV v2 минимальная политика для ключей поставщиков моделей выглядит так: ```hcl theme={"theme":{"light":"min-light","dark":"min-dark"}} path "secret/data/providers/*" { capabilities = ["read"] } ``` ## Предоставление Gateway доступа к Vault Для локального Gateway, работающего без контейнера, экспортируйте настройки Vault в той же оболочке, из которой запускается OpenClaw. Стандартный метод аутентификации считывает клиентский токен Vault из `VAULT_TOKEN`: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} export VAULT_ADDR=https://vault.example.com export VAULT_TOKEN= ``` Если Vault Agent записывает токен в целевой файл, используйте аутентификацию через файл токена: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} export VAULT_ADDR=https://vault.example.com export OPENCLAW_VAULT_AUTH_METHOD=token_file export VAULT_TOKEN_FILE=/vault/secrets/token ``` Если сервер Vault подписан частным центром сертификации, установите этот сертификат ЦС в хранилище доверенных сертификатов узла и включите использование системного хранилища в Node: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} export NODE_USE_SYSTEM_CA=1 ``` Либо укажите пакет сертификатов PEM напрямую: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} export NODE_EXTRA_CA_CERTS=/path/to/vault-ca.pem ``` Эти переменные должны присутствовать при запуске OpenClaw. Плагин Vault передаёт их своему процессу разрешения. Для неинтерактивной аутентификации JWT используйте файл JWT рабочей нагрузки и роль Vault типа `jwt`: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} export VAULT_ADDR=https://vault.example.com export OPENCLAW_VAULT_AUTH_METHOD=jwt export OPENCLAW_VAULT_AUTH_MOUNT=jwt export OPENCLAW_VAULT_AUTH_ROLE=openclaw export OPENCLAW_VAULT_JWT_FILE=/var/run/secrets/tokens/vault ``` Файл JWT должен содержать проецируемый токен рабочей нагрузки, например токен сервисной учётной записи Kubernetes с аудиторией, принимаемой ролью Vault. Интерактивный вход через OIDC в браузере удобен для людей, но среде выполнения Gateway необходим неинтерактивный вход через JWT или файл токена. Для метода аутентификации Kubernetes в Vault используйте `kubernetes`. Он предназначен для Gateway, работающих как Pod; стандартная точка монтирования — `kubernetes`, а стандартный файл JWT находится по обычному пути токена сервисной учётной записи: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} export VAULT_ADDR=https://vault.example.com export OPENCLAW_VAULT_AUTH_METHOD=kubernetes export OPENCLAW_VAULT_AUTH_ROLE=openclaw ``` Задавайте `OPENCLAW_VAULT_AUTH_MOUNT`, только если аутентификация Kubernetes смонтирована в Vault не в `auth/kubernetes`. Задавайте `OPENCLAW_VAULT_JWT_FILE`, только если токен сервисной учётной записи проецируется по нестандартному пути. Необязательные настройки: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} export VAULT_NAMESPACE= export OPENCLAW_VAULT_KV_MOUNT=secret export OPENCLAW_VAULT_KV_VERSION=2 ``` Проверьте, что доступно текущей оболочке: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw vault status ``` Если настроено несколько поставщиков секретов на основе Vault, выберите нужный по псевдониму: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw vault status --provider-alias corp-vault ``` `openclaw vault status` никогда не выводит `VAULT_TOKEN`; команда сообщает только, заданы ли токен, файл токена и файл JWT. Если Gateway работает как служба, LaunchAgent, модуль systemd, запланированная задача или контейнер, эта среда выполнения должна получить те же переменные Vault. Установка переменных в интерактивной оболочке подтверждает их наличие только в этой оболочке, но не в уже запущенном Gateway. ## Создание и применение плана SecretRef Создайте план, сопоставляющий API-ключ поставщика моделей OpenRouter с Vault: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw vault setup \ --plan-out ./vault-secrets-plan.json \ --openrouter-id providers/openrouter/apiKey ``` Примените и проверьте план: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw secrets apply --from ./vault-secrets-plan.json --dry-run --allow-exec openclaw secrets apply --from ./vault-secrets-plan.json --allow-exec openclaw secrets audit --check --allow-exec openclaw secrets reload ``` Используйте `--allow-exec`, поскольку плагин Vault выполняет разрешение через управляемого OpenClaw поставщика SecretRef типа exec. Если Gateway ещё не запущен, после применения плана запустите его обычным способом вместо выполнения `openclaw secrets reload`. ## Настройка дополнительных ключей поставщиков Встроенные сокращения: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw vault setup --openai-id providers/openai/apiKey openclaw vault setup --anthropic-id providers/anthropic/apiKey openclaw vault setup --openrouter-id providers/openrouter/apiKey ``` Несколько ключей поставщиков в одном плане: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw vault setup \ --plan-out ./vault-secrets-plan.json \ --openai-id providers/openai/apiKey \ --anthropic-id providers/anthropic/apiKey \ --openrouter-id providers/openrouter/apiKey ``` Для встроенных поставщиков без сокращений, а также уже настроенных OpenAI-совместимых и пользовательских поставщиков моделей используйте `--provider-key`: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw vault setup \ --plan-out ./vault-secrets-plan.json \ --provider-key local-openai=providers/local-openai/apiKey \ --provider-key groq=providers/groq/apiKey ``` Каждый `--provider-key ` записывает SecretRef в `models.providers..apiKey`. Для пользовательских поставщиков команда не создаёт настройки поставщика `baseUrl`, `api` или `models`; сначала настройте их. Используйте `--target ` для любого известного целевого пути SecretRef: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} openclaw vault setup \ --target channels.telegram.botToken=channels/telegram/botToken \ --target models.providers.openai.headers.x-api-key=providers/openai/proxyKey \ --target auth-profiles:main:profiles.openai.key=providers/openai/apiKey ``` Целевые пути без префикса применяются к `openclaw.json`. Используйте `auth-profiles::` для существующих целей `auth-profiles.json`. Целевой путь должен быть зарегистрированной целью SecretRef в OpenClaw. Команда настройки не создаёт произвольные именованные секреты в OpenClaw: хранилищем секретов остаётся Vault, а OpenClaw сохраняет SecretRef только в поддерживаемых полях конфигурации. ## Формат идентификатора SecretRef Идентификаторы Vault SecretRef используют следующее соглашение: ```text theme={"theme":{"light":"min-light","dark":"min-dark"}} / ``` Примеры: | Идентификатор SecretRef | Стандартное чтение Vault KV v2 | Возвращаемое поле | | ----------------------------- | ---------------------------------- | ----------------- | | `providers/openrouter/apiKey` | `secret/data/providers/openrouter` | `apiKey` | | `providers/openai/apiKey` | `secret/data/providers/openai` | `apiKey` | | `teams/agent-prod/openrouter` | `secret/data/teams/agent-prod` | `openrouter` | Возвращаемое поле Vault должно быть строкой. Для KV v1 задайте: ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}} export OPENCLAW_VAULT_KV_VERSION=1 ``` Тогда `providers/openrouter/apiKey` считывает: ```text theme={"theme":{"light":"min-light","dark":"min-dark"}} secret/providers/openrouter -> apiKey ``` ## Что хранит OpenClaw При применении плана настройки Vault сохраняется управляемый плагином поставщик: ```json theme={"theme":{"light":"min-light","dark":"min-dark"}} { "source": "exec", "pluginIntegration": { "pluginId": "vault", "integrationId": "vault" } } ``` Поля учётных данных ссылаются на этого поставщика: ```json theme={"theme":{"light":"min-light","dark":"min-dark"}} { "source": "exec", "provider": "vault", "id": "providers/openrouter/apiKey" } ``` Разрешённое значение существует только в активном снимке секретов среды выполнения. ## Контейнеры и управляемые развёртывания Gateway в контейнерах используют те же плагин и конфигурацию SecretRef. В контейнер необходимо передать: * `VAULT_ADDR` * один источник аутентификации: * `VAULT_TOKEN` * `OPENCLAW_VAULT_AUTH_METHOD=token_file` вместе с `VAULT_TOKEN_FILE` * `OPENCLAW_VAULT_AUTH_METHOD=jwt` вместе с `OPENCLAW_VAULT_AUTH_MOUNT`, `OPENCLAW_VAULT_AUTH_ROLE` и `OPENCLAW_VAULT_JWT_FILE` * `OPENCLAW_VAULT_AUTH_METHOD=kubernetes` вместе с `OPENCLAW_VAULT_AUTH_ROLE`; при необходимости переопределите `OPENCLAW_VAULT_AUTH_MOUNT` или `OPENCLAW_VAULT_JWT_FILE` * необязательные `VAULT_NAMESPACE`, `OPENCLAW_VAULT_KV_MOUNT` и `OPENCLAW_VAULT_KV_VERSION` При использовании Kubernetes отдавайте предпочтение `OPENCLAW_VAULT_AUTH_METHOD=kubernetes`, если в Vault настроена аутентификация Kubernetes для кластера. Используйте `OPENCLAW_VAULT_AUTH_METHOD=jwt`, только если Vault настроен так, чтобы считать кластер обычным издателем JWT/OIDC. Оба варианта лучше, чем долгоживущий токен Vault в секрете Kubernetes. Развёртывания с дополнительным контейнером Vault Agent или инжектором могут вместо этого использовать `token_file`. В мультитенантных конфигурациях Vault задавайте маршрутизацию арендаторов в политике Vault и конфигурации развёртывания. OpenClaw не требует фиксированных точки монтирования, роли или пути: каждая среда Gateway может задавать собственные `OPENCLAW_VAULT_KV_MOUNT`, `OPENCLAW_VAULT_AUTH_ROLE` и идентификаторы SecretRef. Если один общий Gateway должен одновременно разрешать данные разных пользователей Vault, используйте вручную настроенных поставщиков exec, оборачивающих разные среды аутентификации, либо разделите арендаторов между средами Gateway с отдельными переменными окружения Vault. ## Связанные материалы * [Управление секретами](/ru/gateway/secrets) * [`openclaw secrets`](/ru/cli/secrets) * [Перечень плагинов](/ru/plugins/plugin-inventory)