---
read_when:
- Настройка SecretRefs для учётных данных провайдера и ссылок `auth-profiles.json`
- Безопасная перезагрузка, аудит, настройка и применение секретов в рабочей среде
- Принципы немедленного завершения при ошибке запуска, фильтрации неактивных поверхностей и использования последней заведомо исправной конфигурации
sidebarTitle: Secrets management
summary: 'Управление секретами: контракт SecretRef, поведение снимков среды выполнения и безопасное необратимое удаление секретов'
title: Управление секретами
x-i18n:
generated_at: "2026-07-13T18:13:45Z"
model: gpt-5.6
postprocess_version: locale-links-v1
prompt_version: 24
provider: openai
source_hash: 9fbcac081a7b9bd8bc298b9fb2b7437f3bea4dad85338eed7db4cb4db051cfc7
source_path: gateway/secrets.md
workflow: 16
---
OpenClaw поддерживает аддитивные SecretRef, поэтому поддерживаемые учетные данные не требуется хранить в конфигурации в виде открытого текста.
Открытый текст по-прежнему поддерживается. SecretRef включаются отдельно для каждых учетных данных.
Учетные данные в открытом тексте остаются доступными агенту для чтения, если находятся в файлах, которые агент может проверять, включая `openclaw.json`, `auth-profiles.json`, `.env` или сгенерированные файлы `agents/*/agent/models.json`. SecretRef уменьшают этот локальный радиус поражения только после переноса всех поддерживаемых учетных данных и подтверждения командой `openclaw secrets audit --check` отсутствия остатков открытого текста.
## Модель выполнения
- Секреты разрешаются в хранящийся в памяти снимок среды выполнения заранее при активации, а не отложенно в путях обработки запросов.
- Запуск немедленно завершается ошибкой, если фактически активный SecretRef невозможно разрешить.
- Перезагрузка выполняется как атомарная замена: либо полный успех, либо сохранение последнего заведомо исправного снимка.
- Нарушения политик (например, профиль аутентификации в режиме OAuth в сочетании с вводом SecretRef) приводят к сбою активации до замены снимка среды выполнения.
- Запросы среды выполнения читают только активный снимок в памяти. Учетные данные SecretRef поставщика моделей проходят через хранилище аутентификации и параметры потока в виде локальных для процесса маркеров до момента отправки наружу. Пути исходящей доставки (доставка ответов и сообщений в ветках Discord, отправка действий Telegram) также читают этот снимок и не разрешают ссылки повторно при каждой отправке.
Благодаря этому сбои поставщика секретов не затрагивают горячие пути обработки запросов.
## Подстановка при отправке наружу (маркеры)
Для учетных данных поставщика моделей, основанных на SecretRef, OpenClaw создает непрозрачный локальный для процесса маркер при разрешении аутентификации модели. Поэтому хранилище аутентификации, параметры потока, конфигурация SDK, журналы, объекты ошибок и большинство средств проверки среды выполнения видят значение наподобие `oc-sent-v1-...`, а не учетные данные поставщика. Защищенная функция получения данных модели и управляемые проверки работоспособности локального поставщика заменяют известные маркеры в значениях URL и заголовков непосредственно перед выходом каждого запроса из процесса.
Неизвестные значения, имеющие форму маркера, приводят к отказу до любой сетевой активности. OpenClaw отказывается отправлять запрос вместо передачи поставщику неразрешенного маркера. Разрешенные значения секретов также регистрируются для удаления точных значений из журналов в качестве дополнительной эшелонированной защиты.
Адаптеры поставщиков используют наиболее позднюю точку подстановки, поддерживаемую их SDK:
- SDK с параметром пользовательской функции получения данных получают защищенную функцию OpenClaw, поэтому SDK сохраняет маркер.
- SDK без параметра пользовательской функции получения данных раскрывают маркер непосредственно перед созданием клиента. Потоки поставщиков, принадлежащие плагинам, и среды выполнения агентов раскрывают его на последнем переходе под управлением ядра, поскольку эти транспорты не используют защищенную функцию получения данных OpenClaw.
Маркеры сокращают раскрытие открытого текста по всей цепочке вызова модели, но не обеспечивают изоляцию процессов. Фактическое значение по-прежнему существует в памяти того же процесса и появляется на конечной границе адаптера. Учетные данные из переменных среды, не настроенные через SecretRef, остаются открытым текстом и не охватываются этим механизмом.
Задайте `OPENCLAW_SECRET_SENTINELS=off` (также принимаются `0` или `false` без учета регистра), чтобы отключить создание маркеров при реагировании на инциденты или устранении проблем совместимости. Этот аварийный переключатель не отключает регистрацию точных значений для удаления из журналов.
## Граница доступа агента
SecretRef предотвращают сохранение учетных данных в конфигурации и сгенерированных файлах моделей, но не являются границей изоляции процессов. Учетные данные в открытом тексте, оставленные на диске по пути, доступному агенту для чтения, по-прежнему можно прочитать с помощью файловых или командных инструментов в обход удаления данных на уровне API.
В производственных развертываниях, где учитываются файлы, доступные агенту, считайте миграцию завершенной только при выполнении всех следующих условий:
- Поддерживаемые учетные данные используют SecretRef вместо значений в открытом тексте.
- Остатки устаревшего открытого текста удалены из `openclaw.json`, `auth-profiles.json`, `.env` и сгенерированных файлов `models.json`.
- `openclaw secrets audit --check` не обнаруживает проблем после миграции.
- Все оставшиеся неподдерживаемые или ротируемые учетные данные защищены изоляцией ОС, изоляцией контейнеров или внешним прокси-сервером учетных данных.
Поэтому рабочий процесс аудита, настройки и применения является контрольным этапом миграции безопасности, а не просто вспомогательным средством для удобства.
SecretRef не делают любые доступные для чтения файлы безопасными. Резервные копии, копии конфигураций, старые сгенерированные каталоги моделей и неподдерживаемые классы учетных данных остаются производственными секретами, пока их не удалят, не переместят за пределы границы доверия агента или не изолируют отдельно.
## Фильтрация активных поверхностей
SecretRef проверяются только на фактически активных поверхностях:
- **Включенные поверхности**: неразрешенные ссылки блокируют запуск или перезагрузку.
- **Неактивные поверхности**: неразрешенные ссылки не блокируют запуск или перезагрузку; для них выдается некритическая диагностика `SECRETS_REF_IGNORED_INACTIVE_SURFACE`.
- Отключенные записи каналов или учетных записей.
- Учетные данные канала верхнего уровня, которые не наследует ни одна включенная учетная запись.
- Отключенные поверхности инструментов или функций.
- Ключи конкретных поставщиков веб-поиска, не выбранных параметром `tools.web.search.provider`. В автоматическом режиме (поставщик не задан) ключи проверяются в порядке приоритета для автоматического обнаружения, пока один из них не будет разрешен; после выбора ключи остальных поставщиков становятся неактивными.
- Материалы аутентификации SSH песочницы (`agents.defaults.sandbox.ssh.identityData`, `certificateData`, `knownHostsData`, а также переопределения для отдельных агентов) активны только тогда, когда фактическим сервером песочницы является `ssh`, а режим песочницы отличается от `off`, для агента по умолчанию или включенного агента.
- SecretRef `gateway.remote.token` / `gateway.remote.password` активны при выполнении любого из следующих условий:
- `gateway.mode=remote`
- настроен `gateway.remote.url`
- `gateway.tailscale.mode` имеет значение `serve` или `funnel`
- В локальном режиме без этих удаленных поверхностей: `gateway.remote.token` активен, когда аутентификация по токену может иметь приоритет и токен из переменной среды или настроек аутентификации не задан; `gateway.remote.password` активен только тогда, когда аутентификация по паролю может иметь приоритет и пароль из переменной среды или настроек аутентификации не задан.
- SecretRef `gateway.auth.token` неактивен при разрешении аутентификации во время запуска, когда задан `OPENCLAW_GATEWAY_TOKEN`, поскольку для этой среды выполнения приоритет имеет ввод токена из переменной среды.
## Диагностика поверхности аутентификации Gateway
Если SecretRef задан для `gateway.auth.token`, `gateway.auth.password`, `gateway.remote.token` или `gateway.remote.password`, при запуске или перезагрузке Gateway состояние поверхности записывается в журнал с кодом `SECRETS_GATEWAY_AUTH_SURFACE`:
- `active`: SecretRef входит в фактическую поверхность аутентификации и должен быть разрешен.
- `inactive`: приоритет имеет другая поверхность аутентификации либо удаленная аутентификация отключена или неактивна.
Запись журнала содержит причину, использованную политикой активных поверхностей.
## Предварительная проверка ссылок при первоначальной настройке
При выборе хранения SecretRef во время интерактивной первоначальной настройки перед сохранением выполняется предварительная проверка:
- Ссылки на переменные среды: проверяется имя переменной среды и подтверждается, что во время настройки доступно непустое значение.
- Ссылки поставщика (`file` или `exec`): проверяется выбор поставщика, разрешается `id` и проверяется тип разрешенного значения.
- Процесс быстрой настройки: если `gateway.auth.token` уже является SecretRef, первоначальная настройка разрешает его перед проверкой и начальной настройкой панели управления (для ссылок `env`, `file` и `exec`) с использованием того же механизма немедленного отказа.
При ошибке проверки отображается сообщение об ошибке и предоставляется возможность повторить попытку.
## Контракт SecretRef
Одна форма объекта во всех случаях:
```json5
{ source: "env" | "file" | "exec", provider: "default", id: "..." }
```
```json5
{ source: "env", provider: "default", id: "OPENAI_API_KEY" }
```
В полях SecretInput также принимаются сокращенные строки:
```json5
"${OPENAI_API_KEY}"
"$OPENAI_API_KEY"
```
Проверка:
- `provider` должен соответствовать `^[a-z][a-z0-9_-]{0,63}$`
- `id` должен соответствовать `^[A-Z][A-Z0-9_]{0,127}$`
```json5
{ source: "file", provider: "filemain", id: "/providers/openai/apiKey" }
```
Проверка:
- `provider` должен соответствовать `^[a-z][a-z0-9_-]{0,63}$`
- `id` должен быть абсолютным указателем JSON (`/...`) или литералом `value` для поставщиков `singleValue`
- Экранирование RFC 6901 в сегментах: `~` преобразуется в `~0`, `/` преобразуется в `~1`
```json5
{ source: "exec", provider: "vault", id: "providers/openai/apiKey#value" }
```
Проверка:
- `provider` должен соответствовать `^[a-z][a-z0-9_-]{0,63}$`
- `id` должен соответствовать `^[A-Za-z0-9][A-Za-z0-9._:/#-]{0,255}$` (поддерживаются селекторы, например `secret#json_key`)
- `id` не должен содержать `.` или `..` в качестве сегментов пути, разделенных косой чертой (например, `a/../b` отклоняется)
## Конфигурация поставщика
Определите поставщиков в разделе `secrets.providers`:
```json5
{
secrets: {
providers: {
default: { source: "env" },
filemain: {
source: "file",
path: "~/.openclaw/secrets.json",
mode: "json", // or "singleValue"
},
vault: {
source: "exec",
command: "/usr/local/bin/openclaw-vault-resolver",
args: ["--profile", "prod"],
passEnv: ["PATH", "VAULT_ADDR"],
jsonOnly: true,
},
"team-secrets": {
source: "exec",
pluginIntegration: {
pluginId: "acme-secrets",
integrationId: "secret-store",
},
},
},
defaults: {
env: "default",
file: "filemain",
exec: "vault",
},
resolution: {
maxProviderConcurrency: 4,
maxRefsPerProvider: 512,
maxBatchBytes: 262144,
},
},
}
```
- Необязательный список разрешенных точных имен через `allowlist`.
- Отсутствующие или пустые значения переменных среды приводят к ошибке разрешения.
- Читает локальный файл по пути `path`.
- `mode: "json"` (по умолчанию) ожидает полезную нагрузку в виде объекта JSON и разрешает `id` как указатель JSON.
- `mode: "singleValue"` ожидает идентификатор ссылки `"value"` и возвращает необработанное содержимое файла (конечный символ новой строки удаляется).
- Путь должен пройти проверки владельца и разрешений; `timeoutMs` (по умолчанию 5000) и `maxBytes` (по умолчанию 1 MiB) ограничивают чтение.
- Отказ по умолчанию в Windows: если проверка ACL для пути недоступна, разрешение завершается ошибкой. Только для доверенных путей задайте `allowInsecurePath: true` для этого поставщика, чтобы обойти проверку.
- Запускает настроенный исполняемый файл по абсолютному пути напрямую, без оболочки.
- По умолчанию `command` должен быть обычным файлом, а не символической ссылкой. Установите `allowSymlinkCommand: true`, чтобы разрешить пути команд через символические ссылки (например, обёртки Homebrew), и используйте его вместе с `trustedDirs` (например, `["/opt/homebrew"]`), чтобы подходили только пути менеджера пакетов.
- Поддерживает `timeoutMs` (по умолчанию 5000), `noOutputTimeoutMs` (по умолчанию равно `timeoutMs`), `maxOutputBytes` (по умолчанию 1 MiB), список разрешённых значений `env`/`passEnv` и `trustedDirs`.
- По умолчанию `jsonOnly` имеет значение `true`. При наличии `jsonOnly: false` и запросе одного идентификатора обычный вывод stdout не в формате JSON принимается как значение этого идентификатора.
- Безопасный отказ в Windows: если для пути команды невозможно проверить ACL, разрешение завершается ошибкой. Только для доверенных путей установите `allowInsecurePath: true` у этого провайдера, чтобы пропустить проверку.
- Exec-провайдеры, управляемые плагинами, могут использовать `pluginIntegration` вместо скопированных `command`/`args`. OpenClaw получает актуальные сведения о команде из манифеста установленного плагина при запуске или перезагрузке; если плагин отключён, удалён, не является доверенным или больше не объявляет интеграцию, активные SecretRef этого провайдера безопасно завершаются ошибкой.
Полезная нагрузка запроса (stdin):
```json
{ "protocolVersion": 1, "provider": "vault", "ids": ["providers/openai/apiKey"] }
```
Полезная нагрузка ответа (stdout):
```jsonc
{ "protocolVersion": 1, "values": { "providers/openai/apiKey": "" } } // pragma: секрет из списка разрешённых
```
Необязательные ошибки для отдельных идентификаторов:
```json
{
"protocolVersion": 1,
"values": {},
"errors": { "providers/openai/apiKey": { "code": "NOT_FOUND" } }
}
```
`code` — необязательное машиночитаемое диагностическое сообщение. OpenClaw отображает распознанные
коды `NOT_FOUND` и `AMBIGUOUS_DUPLICATE_KEY` вместе с провайдером и идентификатором ссылки. Другие
коды и поля произвольного формата, такие как `message`, принимаются для совместимости с протоколом версии 1,
но не отображаются, поскольку вывод средства разрешения может содержать учётные данные.
## API-ключи из файлов
Не помещайте строки `file:...` в блок `env` конфигурации. Этот блок является буквальным и не допускает переопределения, поэтому `file:...` в нём никогда не разрешается.
Вместо этого используйте файловый SecretRef в поддерживаемом поле учётных данных:
```json5
{
secrets: {
providers: {
xai_key_file: {
source: "file",
path: "~/.openclaw/secrets/xai-api-key.txt",
mode: "singleValue",
},
},
},
models: {
providers: {
xai: {
apiKey: { source: "file", provider: "xai_key_file", id: "value" },
},
},
},
}
```
Для `mode: "singleValue"` значение `id` в SecretRef — `"value"`. Для `mode: "json"` используйте абсолютный указатель JSON, например `"/providers/xai/apiKey"`.
Поля, принимающие SecretRef, перечислены в разделе [Поверхность учётных данных SecretRef](/ru/reference/secretref-credential-surface).
## Примеры интеграции Exec
Специальное руководство по 1Password, посвящённое сервисным аккаунтам, встроенному навыку агента и устранению неполадок, см. в разделе [1Password](/gateway/1password).
```json5
{
secrets: {
providers: {
onepassword_openai: {
source: "exec",
command: "/opt/homebrew/bin/op",
allowSymlinkCommand: true, // требуется для исполняемых файлов Homebrew, доступных через символические ссылки
trustedDirs: ["/opt/homebrew"],
args: ["read", "op://Personal/OpenClaw QA API Key/password"],
passEnv: ["HOME"],
jsonOnly: false,
},
},
},
models: {
providers: {
openai: {
baseUrl: "https://api.openai.com/v1",
models: [{ id: "gpt-5", name: "gpt-5" }],
apiKey: { source: "exec", provider: "onepassword_openai", id: "value" },
},
},
},
}
```
Используйте обёртку средства разрешения, чтобы сопоставлять идентификаторы SecretRef с ключами элементов Bitwarden Secrets Manager. Репозиторий содержит `scripts/secrets/openclaw-bws-resolver.mjs`; установите или скопируйте его в абсолютный доверенный путь на хосте, где работает Gateway.
Требования:
- CLI Bitwarden Secrets Manager (`bws`) установлен на хосте Gateway.
- `BWS_ACCESS_TOKEN` доступен службе Gateway.
- `PATH` передаётся средству разрешения либо `BWS_BIN` содержит абсолютный путь к исполняемому файлу `bws`.
- При использовании самостоятельно размещённого экземпляра Bitwarden в окружении задано `BWS_SERVER_URL`.
```json5
{
secrets: {
providers: {
bws: {
source: "exec",
command: "/usr/local/bin/openclaw-bws-resolver.mjs",
passEnv: ["BWS_ACCESS_TOKEN", "BWS_SERVER_URL", "PATH", "BWS_BIN"],
jsonOnly: true,
},
},
},
models: {
providers: {
openai: {
baseUrl: "https://api.openai.com/v1",
models: [{ id: "gpt-5", name: "gpt-5" }],
apiKey: {
source: "exec",
provider: "bws",
id: "openclaw/providers/openai/apiKey",
},
},
},
},
}
```
Средство разрешения объединяет запрошенные идентификаторы в пакет, выполняет `bws secret list` и возвращает значения соответствующих полей `key` секретов. Используйте ключи, соответствующие контракту идентификаторов Exec SecretRef, например `openclaw/providers/openai/apiKey`; ключи в стиле переменных окружения с символами подчёркивания отклоняются до запуска средства разрешения. Если один и тот же запрошенный ключ имеют несколько видимых секретов Bitwarden, средство разрешения помечает этот идентификатор как неоднозначный и завершается ошибкой вместо выбора наугад. После обновления конфигурации проверьте путь средства разрешения:
```bash
openclaw secrets audit --allow-exec
```
```json5
{
secrets: {
providers: {
vault_openai: {
source: "exec",
command: "/opt/homebrew/bin/vault",
allowSymlinkCommand: true, // требуется для исполняемых файлов Homebrew, доступных через символические ссылки
trustedDirs: ["/opt/homebrew"],
args: ["kv", "get", "-field=OPENAI_API_KEY", "secret/openclaw"],
passEnv: ["VAULT_ADDR", "VAULT_TOKEN"],
jsonOnly: false,
},
},
},
models: {
providers: {
openai: {
baseUrl: "https://api.openai.com/v1",
models: [{ id: "gpt-5", name: "gpt-5" }],
apiKey: { source: "exec", provider: "vault_openai", id: "value" },
},
},
},
}
```
Используйте небольшую обёртку средства разрешения, чтобы напрямую сопоставлять идентификаторы SecretRef с записями `pass`. Сохраните её как исполняемый файл по абсолютному пути, проходящему проверки путей Exec-провайдера, например `/usr/local/bin/openclaw-pass-resolver`. Строка shebang `#!/usr/bin/env node` находит `node` через `PATH` процесса средства разрешения, поэтому включите `PATH` в `passEnv`. Если `pass` отсутствует в этом `PATH`, задайте `PASS_BIN` в родительском окружении и также включите его в `passEnv`:
```js
#!/usr/bin/env node
const { spawnSync } = require("node:child_process");
let stdin = "";
process.stdin.setEncoding("utf8");
process.stdin.on("data", (chunk) => {
stdin += chunk;
});
process.stdin.on("error", (err) => {
process.stderr.write(`${err.message}\n`);
process.exit(1);
});
process.stdin.on("end", () => {
let request;
try {
request = JSON.parse(stdin || "{}");
} catch (err) {
process.stderr.write(`Не удалось разобрать запрос: ${err.message}\n`);
process.exit(1);
}
const passBin = process.env.PASS_BIN || "pass";
const values = {};
const errors = {};
for (const id of request.ids ?? []) {
const result = spawnSync(passBin, ["show", id], { encoding: "utf8" });
if (result.status === 0) {
values[id] = result.stdout.split(/\r?\n/, 1)[0] ?? "";
} else {
errors[id] = { message: (result.stderr || `pass завершился с кодом ${result.status}`).trim() };
}
}
process.stdout.write(JSON.stringify({ protocolVersion: 1, values, errors }));
});
```
Затем настройте Exec-провайдер и укажите в `apiKey` путь к записи `pass`:
```json5
{
secrets: {
providers: {
pass_store: {
source: "exec",
command: "/usr/local/bin/openclaw-pass-resolver",
passEnv: ["PATH", "HOME", "GNUPGHOME", "GPG_TTY", "PASSWORD_STORE_DIR", "PASS_BIN"],
jsonOnly: true,
},
},
},
models: {
providers: {
openai: {
baseUrl: "https://api.openai.com/v1",
models: [{ id: "gpt-5", name: "gpt-5" }],
apiKey: {
source: "exec",
provider: "pass_store",
id: "openclaw/providers/openai/apiKey",
},
},
},
},
}
```
Храните секрет в первой строке записи `pass` либо измените обёртку так, чтобы вместо этого она возвращала полный вывод `pass show`. После обновления конфигурации проверьте как статический аудит, так и путь Exec-средства разрешения:
```bash
openclaw secrets audit --check
openclaw secrets audit --allow-exec
```
```json5
{
secrets: {
providers: {
sops_openai: {
source: "exec",
command: "/opt/homebrew/bin/sops",
allowSymlinkCommand: true, // требуется для исполняемых файлов Homebrew, доступных через символические ссылки
trustedDirs: ["/opt/homebrew"],
args: ["-d", "--extract", '["providers"]["openai"]["apiKey"]', "/path/to/secrets.enc.json"],
passEnv: ["SOPS_AGE_KEY_FILE"],
jsonOnly: false,
},
},
},
models: {
providers: {
openai: {
baseUrl: "https://api.openai.com/v1",
models: [{ id: "gpt-5", name: "gpt-5" }],
apiKey: { source: "exec", provider: "sops_openai", id: "value" },
},
},
},
}
```
## Переменные окружения сервера MCP
Переменные окружения сервера MCP, настроенные через `plugins.entries.acpx.config.mcpServers`, принимают SecretInput, что позволяет не хранить API-ключи и токены в конфигурации открытым текстом:
```json5
{
plugins: {
entries: {
acpx: {
enabled: true,
config: {
mcpServers: {
github: {
command: "npx",
args: ["-y", "@modelcontextprotocol/server-github"],
env: {
GITHUB_PERSONAL_ACCESS_TOKEN: {
source: "env",
provider: "default",
id: "MCP_GITHUB_PAT",
},
},
},
},
},
},
},
},
}
```
Строковые значения открытым текстом по-прежнему поддерживаются. Ссылки на шаблоны переменных окружения, такие как `${MCP_SERVER_API_KEY}`, и объекты SecretRef разрешаются во время активации Gateway до запуска процесса сервера MCP. Как и для других поверхностей SecretRef, неразрешённые ссылки блокируют активацию, только когда плагин `acpx` фактически активен.
## Материалы аутентификации SSH для песочницы
Базовый бэкенд песочницы `ssh` также поддерживает SecretRef для материалов аутентификации SSH:
```json5
{
agents: {
defaults: {
sandbox: {
mode: "all",
backend: "ssh",
ssh: {
target: "user@gateway-host:22",
identityData: { source: "env", provider: "default", id: "SSH_IDENTITY" },
certificateData: { source: "env", provider: "default", id: "SSH_CERTIFICATE" },
knownHostsData: { source: "env", provider: "default", id: "SSH_KNOWN_HOSTS" },
},
},
},
},
}
```
Поведение среды выполнения:
- OpenClaw разрешает эти ссылки при активации песочницы, а не отложенно при каждом вызове SSH.
- Разрешённые значения записываются во временный каталог со строгими разрешениями файлов (`0o600`) и используются в создаваемой конфигурации SSH.
- Если фактическим бэкендом песочницы является не `ssh` (или режим песочницы — `off`), эти ссылки остаются неактивными и не блокируют запуск.
## Поддерживаемая область учётных данных
Канонический список поддерживаемых и неподдерживаемых учётных данных приведён в разделе [Область учётных данных SecretRef](/ru/reference/secretref-credential-surface).
Учётные данные, создаваемые средой выполнения или регулярно сменяемые, а также данные обновления OAuth намеренно исключены из разрешения SecretRef только для чтения.
## Обязательное поведение и приоритет
- Поле без ссылки: без изменений.
- Поле со ссылкой: обязательно на активных поверхностях во время активации.
- Если присутствуют и открытый текст, и ссылка, на поддерживаемых путях определения приоритета ссылка имеет приоритет.
- Маркер редактирования `__OPENCLAW_REDACTED__` зарезервирован для внутреннего редактирования и восстановления конфигурации и отклоняется, если отправлен как буквальное значение конфигурации.
Сигналы предупреждений и аудита:
- `SECRETS_REF_OVERRIDES_PLAINTEXT` (предупреждение среды выполнения)
- `REF_SHADOWED` (результат аудита, когда учётные данные `auth-profiles.json` имеют приоритет над ссылками `openclaw.json`)
Совместимость с Google Chat: `serviceAccountRef` имеет приоритет над значением `serviceAccount` в открытом виде; после установки соседней ссылки значение в открытом виде игнорируется.
## Триггеры активации
Активация секретов выполняется при:
- Запуске (предварительная и окончательная активация)
- Горячем применении при перезагрузке конфигурации
- Проверке необходимости перезапуска при перезагрузке конфигурации
- Ручной перезагрузке через `secrets.reload`
- Предварительной проверке RPC записи конфигурации Gateway (`config.set` / `config.apply` / `config.patch`), которая до сохранения изменений проверяет возможность разрешения SecretRef активной поверхности в отправленных данных конфигурации
Контракт активации:
- При успехе снимок заменяется атомарно.
- Ошибка при запуске прерывает запуск Gateway.
- При ошибке перезагрузки во время работы сохраняется последний заведомо исправный снимок.
- Ошибка предварительной проверки RPC записи отклоняет отправленную конфигурацию; конфигурация на диске и активный снимок среды выполнения остаются без изменений.
- Передача явного токена канала для отдельного вызова вспомогательной функции или инструмента отправки не запускает активацию SecretRef; точками активации остаются запуск, перезагрузка и явный вызов `secrets.reload`.
## Сигналы ухудшения и восстановления
Если активация при перезагрузке завершается сбоем после исправного состояния, OpenClaw переходит в состояние ухудшенной доступности секретов, однократно создавая системные события и коды журналов:
- `SECRETS_RELOADER_DEGRADED`
- `SECRETS_RELOADER_RECOVERED`
Поведение:
- Ухудшение: среда выполнения сохраняет последний заведомо исправный снимок.
- Восстановление: событие создаётся один раз после следующей успешной активации.
- Повторные сбои при уже ухудшенном состоянии записывают предупреждения в журнал, но не создают событие повторно.
- Быстрое завершение при ошибке запуска никогда не создаёт событие ухудшения, поскольку среда выполнения не успела стать активной.
## Разрешение в путях команд
Пути команд могут использовать поддерживаемое разрешение SecretRef через RPC снимка Gateway. Применяются два основных варианта поведения:
Например, пути удалённой памяти `openclaw memory` и `openclaw qr --remote`, когда ему требуются удалённые ссылки на общие секреты. Они читают данные из активного снимка и немедленно завершаются ошибкой, если обязательная SecretRef недоступна.
Например, `openclaw status`, `openclaw status --all`, `openclaw channels status`, `openclaw channels resolve`, `openclaw security audit`, а также потоки doctor и исправления конфигурации только для чтения. Они также предпочитают активный снимок, но при недоступности целевой SecretRef переходят в ухудшенный режим вместо прерывания.
Поведение только для чтения:
- Когда Gateway работает, эти команды сначала читают данные из активного снимка.
- Если разрешение через Gateway неполно или Gateway недоступен, они пытаются выполнить целевое локальное резервное разрешение для поверхности этой команды.
- Если целевая SecretRef по-прежнему недоступна, команда продолжает работу с ухудшенным выводом только для чтения и явной диагностикой о том, что ссылка настроена, но недоступна в этом пути команды.
- Это ухудшенное поведение применяется только к конкретной команде; оно не ослабляет требования к запуску среды выполнения, перезагрузке и путям отправки или аутентификации.
Другие примечания:
- Обновление снимка после смены секрета в бэкенде выполняется с помощью `openclaw secrets reload`.
- Метод RPC Gateway, используемый этими путями команд: `secrets.resolve`.
## Процесс аудита и настройки
Стандартный процесс оператора:
```bash
openclaw secrets audit --check
```
```bash
openclaw secrets configure --apply
```
```bash
openclaw secrets audit --check
```
Не считайте миграцию завершённой, пока повторный аудит не будет пройден без замечаний. Если аудит по-прежнему сообщает о хранящихся значениях в открытом виде, риск доступа агента сохраняется, даже когда API среды выполнения возвращают отредактированные значения.
Если во время `configure` вы сохраняете план вместо его применения, примените сохранённый план с помощью `openclaw secrets apply --from ` до повторного аудита.
Результаты включают:
- Хранящиеся значения в открытом виде (`openclaw.json`, `auth-profiles.json`, `.env` и созданный `agents/*/agent/models.json`).
- Остаточные конфиденциальные заголовки провайдеров в открытом виде в созданных записях `models.json`.
- Неразрешённые ссылки.
- Затенение по приоритету (`auth-profiles.json` имеет приоритет над ссылками `openclaw.json`).
- Устаревшие остаточные данные (`auth.json`, напоминания OAuth).
Примечание об exec: по умолчанию аудит пропускает проверки возможности разрешения SecretRef через exec, чтобы избежать побочных эффектов команд. Используйте `openclaw secrets audit --allow-exec`, чтобы выполнять провайдеры exec во время аудита.
Примечание об остаточных заголовках: обнаружение конфиденциальных заголовков провайдеров основано на эвристике имён (распространённые имена и фрагменты заголовков аутентификации и учётных данных, такие как `authorization`, `x-api-key`, `token`, `secret`, `password` и `credential`).
Интерактивный помощник, который:
- Сначала настраивает `secrets.providers` (`env`/`file`/`exec`, добавление, изменение или удаление).
- Позволяет выбрать поддерживаемые поля с секретами в `openclaw.json`, а также `auth-profiles.json` для области одного агента.
- Может создать новое сопоставление `auth-profiles.json` непосредственно в средстве выбора цели.
- Получает сведения SecretRef (`source`, `provider`, `id`).
- Выполняет предварительное разрешение и может немедленно применить изменения.
Примечание об exec: предварительная проверка пропускает проверки SecretRef через exec, если не задан `--allow-exec`. Если вы применяете изменения непосредственно из `configure --apply` и план содержит ссылки или провайдеры exec, оставьте `--allow-exec` заданным и на этапе применения.
Полезные режимы:
- `openclaw secrets configure --providers-only`
- `openclaw secrets configure --skip-provider-setup`
- `openclaw secrets configure --agent `
Действия по умолчанию при применении `configure`:
- Удалять совпадающие статические учётные данные из `auth-profiles.json` для целевых провайдеров.
- Удалять устаревшие статические записи `api_key` из `auth.json`.
- Удалять совпадающие известные строки секретов из `/.env`.
Применение сохранённого плана:
```bash
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --allow-exec
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run --allow-exec
```
Примечание об exec: пробный запуск пропускает проверки exec, если не задан `--allow-exec`; режим записи отклоняет планы, содержащие SecretRef или провайдеры exec, если не задан `--allow-exec`.
Подробности строгого контракта целей и путей, а также точные правила отклонения см. в разделе [Контракт плана применения секретов](/ru/gateway/secrets-plan-contract).
## Односторонняя политика безопасности
OpenClaw намеренно не создаёт резервные копии для отката, содержащие прежние значения секретов в открытом виде.
Модель безопасности:
- Перед режимом записи предварительная проверка должна завершиться успешно.
- Активация среды выполнения проверяется до фиксации.
- При применении файлы обновляются с помощью атомарной замены, а при сбое по возможности восстанавливаются.
## Примечания о совместимости с устаревшей аутентификацией
Для статических учётных данных среда выполнения больше не зависит от устаревшего хранилища аутентификационных данных в открытом виде.
- Источником учётных данных среды выполнения является разрешённый снимок в памяти.
- Обнаруженные устаревшие статические записи `api_key` удаляются.
- Поведение совместимости, связанное с OAuth, остаётся отдельным.
## Примечание о веб-интерфейсе
Некоторые объединения SecretInput проще настраивать в режиме редактора исходного текста, чем в режиме формы.
## Связанные разделы
- [Аутентификация](/ru/gateway/authentication) — настройка аутентификации
- [CLI: секреты](/ru/cli/secrets) — команды CLI
- [SecretRef в Vault](/ru/plugins/vault) — настройка провайдера HashiCorp Vault
- [Переменные окружения](/ru/help/environment) — приоритет переменных окружения
- [Область учётных данных SecretRef](/ru/reference/secretref-credential-surface) — область учётных данных
- [Контракт плана применения секретов](/ru/gateway/secrets-plan-contract) — подробности контракта плана
- [Безопасность](/ru/gateway/security) — подход к безопасности