Конфигурация и операции

Управление секретами

OpenClaw поддерживает аддитивные SecretRefs, поэтому поддерживаемые учетные данные не нужно хранить в открытом виде в конфигурации. Обычный текст по-прежнему работает. SecretRefs включаются опционально для каждого учетного поля.

Цели и модель выполнения

Секреты разрешаются в снимок состояния в памяти.

Разрешение происходит активно во время активации, а не лениво на путях запросов.
Запуск завершается с ошибкой при невозможности разрешить фактически активный SecretRef.
Перезагрузка использует атомарную замену: полный успех или сохранение последнего известного рабочего снимка.
Запросы во время выполнения читают только из активного снимка в памяти.

Это позволяет избежать влияния сбоев провайдеров секретов на активные пути запросов.

Фильтрация активных поверхностей

SecretRefs проверяются только на фактически активных поверхностях.

Включенные поверхности: неразрешенные ссылки блокируют запуск/перезагрузку.
Неактивные поверхности: неразрешенные ссылки не блокируют запуск/перезагрузку.
Неактивные ссылки генерируют нефатальные диагностические сообщения с кодом SECRETS_REF_IGNORED_INACTIVE_SURFACE.

Примеры неактивных поверхностей:

Отключенные записи каналов/аккаунтов.
Учетные данные канала верхнего уровня, которые не наследуются ни одним включенным аккаунтом.
Отключенные поверхности инструментов/функций.
Ключи, специфичные для провайдера веб-поиска, который не выбран в tools.web.search.provider. В автоматическом режиме (провайдер не задан) провайдер-специфичные ключи также активны для автоопределения провайдера.
SecretRefs gateway.remote.token / gateway.remote.password активны (когда gateway.remote.enabled не false), если верно одно из условий:
- gateway.mode=remote
- настроен gateway.remote.url
- gateway.tailscale.mode имеет значение serve или funnel В локальном режиме без этих удаленных поверхностей:
- gateway.remote.token активен, когда аутентификация по токену может победить и не настроен токен env/auth.
- gateway.remote.password активен только когда аутентификация по паролю может победить и не настроен пароль env/auth.
SecretRef gateway.auth.token неактивен для разрешения аутентификации при запуске, когда установлена переменная OPENCLAW_GATEWAY_TOKEN (или CLAWDBOT_GATEWAY_TOKEN), потому что токен из окружения имеет приоритет для этого запуска.

Диагностика поверхности аутентификации шлюза

Когда SecretRef настроен для gateway.auth.token, gateway.auth.password, gateway.remote.token или gateway.remote.password, запуск/перезагрузка шлюза явно логирует состояние поверхности:

active: SecretRef является частью эффективной поверхности аутентификации и должен быть разрешен.
inactive: SecretRef игнорируется для этого запуска, потому что другая поверхность аутентификации побеждает, или потому что удаленная аутентификация отключена/не активна.

Эти записи логируются с кодом SECRETS_GATEWAY_AUTH_SURFACE и включают причину, используемую политикой активной поверхности, чтобы вы могли видеть, почему учетные данные были обработаны как активные или неактивные.

Предварительная проверка при онбординге

Когда онбординг запускается в интерактивном режиме и вы выбираете хранение через SecretRef, OpenClaw выполняет предварительную проверку перед сохранением:

Ссылки на переменные окружения (env): проверяет имя переменной и подтверждает, что непустое значение видно во время онбординга.
Ссылки на провайдеров (file или exec): проверяет выбор провайдера, разрешает id и проверяет тип разрешенного значения.
Путь повторного использования быстрого старта: когда gateway.auth.token уже является SecretRef, онбординг разрешает его перед проверкой/загрузкой панели управления (для ссылок env, file и exec) с использованием того же строгого контроля.

Если проверка не удалась, онбординг показывает ошибку и позволяет повторить попытку.

Контракт SecretRef

Используйте одну форму объекта везде:

{ source: "env" | "file" | "exec", provider: "default", id: "..." }

source: "env"

{ source: "env", provider: "default", id: "OPENAI_API_KEY" }

Проверка:

provider должен соответствовать ^[a-z][a-z0-9_-]{0,63}$
id должен соответствовать ^[A-Z][A-Z0-9_]{0,127}$

source: "file"

{ source: "file", provider: "filemain", id: "/providers/openai/apiKey" }

Проверка:

provider должен соответствовать ^[a-z][a-z0-9_-]{0,63}$
id должен быть абсолютным JSON-указателем (/...)
Экранирование RFC6901 в сегментах: ~ => ~0, / => ~1

source: "exec"

{ source: "exec", provider: "vault", id: "providers/openai/apiKey" }

Проверка:

provider должен соответствовать ^[a-z][a-z0-9_-]{0,63}$
id должен соответствовать ^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$

Конфигурация провайдера

Определите провайдеров в secrets.providers:

{
  secrets: {
    providers: {
      default: { source: "env" },
      filemain: {
        source: "file",
        path: "~/.openclaw/secrets.json",
        mode: "json", // или "singleValue"
      },
      vault: {
        source: "exec",
        command: "/usr/local/bin/openclaw-vault-resolver",
        args: ["--profile", "prod"],
        passEnv: ["PATH", "VAULT_ADDR"],
        jsonOnly: true,
      },
    },
    defaults: {
      env: "default",
      file: "filemain",
      exec: "vault",
    },
    resolution: {
      maxProviderConcurrency: 4,
      maxRefsPerProvider: 512,
      maxBatchBytes: 262144,
    },
  },
}

Провайдер переменных окружения (Env)

Опциональный разрешительный список через allowlist.
Отсутствующие/пустые значения переменных окружения приводят к сбою разрешения.

Файловый провайдер (File)

Читает локальный файл по path.
mode: "json" ожидает полезную нагрузку в виде объекта JSON и разрешает id как указатель.
mode: "singleValue" ожидает идентификатор ссылки "value" и возвращает содержимое файла.
Путь должен пройти проверки владения/разрешений.
Примечание для Windows (закрытый режим при сбое): если проверка ACL недоступна для пути, разрешение завершается сбоем. Только для доверенных путей установите allowInsecurePath: true для этого провайдера, чтобы обойти проверки безопасности пути.

Провайдер выполнения (Exec)

Запускает настроенный абсолютный путь к бинарному файлу, без оболочки.
По умолчанию command должен указывать на обычный файл (не символьную ссылку).
Установите allowSymlinkCommand: true, чтобы разрешить пути команд-символьных ссылок (например, для шимов Homebrew). OpenClaw проверяет разрешенный целевой путь.
Используйте allowSymlinkCommand вместе с trustedDirs для путей менеджеров пакетов (например, ["/opt/homebrew"]).
Поддерживает таймаут, таймаут отсутствия вывода, ограничения на размер вывода, разрешительный список переменных окружения и доверенные каталоги.
Примечание для Windows (закрытый режим при сбое): если проверка ACL недоступна для пути команды, разрешение завершается сбоем. Только для доверенных путей установите allowInsecurePath: true для этого провайдера, чтобы обойти проверки безопасности пути.

Полезная нагрузка запроса (stdin):

{ "protocolVersion": 1, "provider": "vault", "ids": ["providers/openai/apiKey"] }

Полезная нагрузка ответа (stdout):

{ "protocolVersion": 1, "values": { "providers/openai/apiKey": "<openai-api-key>" } } // pragma: allowlist secret

Опциональные ошибки для каждого id:

{
  "protocolVersion": 1,
  "values": {},
  "errors": { "providers/openai/apiKey": { "message": "not found" } }
}

Примеры интеграции с Exec

1Password CLI

{
  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" },
      },
    },
  },
}

HashiCorp Vault CLI

{
  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" },
      },
    },
  },
}

sops

{
  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" },
      },
    },
  },
}

Поддерживаемая поверхность учетных данных

Канонический список поддерживаемых и неподдерживаемых учетных данных приведен в:

Поверхность учетных данных SecretRef

Динамически создаваемые или ротирующиеся учетные данные, а также материал для обновления OAuth намеренно исключены из разрешения SecretRef только для чтения.

Требуемое поведение и приоритет

Поле без ссылки: без изменений.
Поле со ссылкой: обязательно на активных поверхностях во время активации.
Если присутствуют и обычный текст, и ссылка, ссылка имеет приоритет на поддерживаемых путях приоритета.

Предупреждения и сигналы аудита:

SECRETS_REF_OVERRIDES_PLAINTEXT (предупреждение во время выполнения)
REF_SHADOWED (результат аудита, когда учетные данные auth-profiles.json имеют приоритет над ссылками в openclaw.json)

Поведение совместимости с Google Chat:

serviceAccountRef имеет приоритет над обычным текстом serviceAccount.
Обычное текстовое значение игнорируется, когда установлена ссылка-сосед.

Триггеры активации

Активация секретов выполняется при:

Запуске (предварительная проверка плюс финальная активация)
Пути горячего применения перезагрузки конфигурации
Пути проверки перезапуска при перезагрузке конфигурации
Ручной перезагрузке через secrets.reload

Контракт активации:

Успех атомарно заменяет снимок.
Сбой при запуске прерывает запуск шлюза.
Сбой перезагрузки во время выполнения сохраняет последний известный рабочий снимок.

Сигналы деградации и восстановления

Когда активация во время перезагрузки завершается сбоем после здорового состояния, OpenClaw переходит в состояние деградации секретов. Одноразовые системные события и коды журнала:

SECRETS_RELOADER_DEGRADED
SECRETS_RELOADER_RECOVERED

Поведение:

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

Разрешение в путях команд

Пути команд могут использовать поддерживаемое разрешение SecretRef через RPC-снимок шлюза. Существует два основных типа поведения:

Строгие пути команд (например, пути удаленной памяти openclaw memory и openclaw qr --remote) читают из активного снимка и немедленно завершаются сбоем, когда требуемый SecretRef недоступен.
Пути команд только для чтения (например, openclaw status, openclaw status --all, openclaw channels status, openclaw channels resolve и потоки восстановления конфигурации/диагностики только для чтения) также предпочитают активный снимок, но деградируют вместо прерывания, когда целевой SecretRef недоступен в этом пути команды.

Поведение только для чтения:

Когда шлюз работает, эти команды сначала читают из активного снимка.
Если разрешение шлюза не завершено или шлюз недоступен, они пытаются выполнить целевое локальное резервное копирование для конкретной поверхности команды.
Если целевой SecretRef все еще недоступен, команда продолжает работу с деградированным выводом только для чтения и явными диагностическими сообщениями, такими как «настроено, но недоступно в этом пути команды».
Это деградированное поведение является локальным только для команды. Оно не ослабляет запуск, перезагрузку или пути отправки/аутентификации среды выполнения.

Другие примечания:

Обновление снимка после ротации секретов в бэкенде обрабатывается командой openclaw secrets reload.
RPC-метод шлюза, используемый этими путями команд: secrets.resolve.

Рабочий процесс аудита и настройки

Стандартный поток оператора:

openclaw secrets audit --check
openclaw secrets configure
openclaw secrets audit --check

secrets audit

Результаты включают:

обычные текстовые значения в хранилище (openclaw.json, auth-profiles.json, .env и сгенерированные agents/*/agent/models.json)
остатки обычных текстовых чувствительных заголовков провайдеров в сгенерированных записях models.json
неразрешенные ссылки
затенение приоритета (приоритет auth-profiles.json над ссылками в openclaw.json)
устаревшие остатки (auth.json, напоминания об OAuth)

Примечание об остатках заголовков:

Обнаружение чувствительных заголовков провайдеров основано на эвристике имен (распространенные имена и фрагменты заголовков аутентификации/учетных данных, такие как authorization, x-api-key, token, secret, password и credential).

secrets configure

Интерактивный помощник, который:

сначала настраивает secrets.providers (env/file/exec, добавить/изменить/удалить)
позволяет выбрать поддерживаемые поля с секретами в openclaw.json плюс auth-profiles.json для одной области агента
может создать новое сопоставление auth-profiles.json непосредственно в целевом средстве выбора
захватывает детали SecretRef (source, provider, id)
выполняет предварительное разрешение
может применить изменения немедленно

Полезные режимы:

openclaw secrets configure --providers-only
openclaw secrets configure --skip-provider-setup
openclaw secrets configure --agent <id>

Правила применения configure по умолчанию:

удаляет соответствующие статические учетные данные из auth-profiles.json для целевых провайдеров
удаляет устаревшие статические записи api_key из auth.json
удаляет соответствующие известные строки с секретами из <config-dir>/.env

secrets apply

Применить сохраненный план:

openclaw secrets apply --from /tmp/openclaw-secrets-plan.json
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run

Подробности строгого контракта цели/пути и точные правила отклонения см. в:

Контракт плана применения секретов

Политика односторонней безопасности

OpenClaw намеренно не создает резервные копии для отката, содержащие исторические обычные текстовые значения секретов. Модель безопасности:

предварительная проверка должна завершиться успешно перед режимом записи
активация среды выполнения проверяется перед фиксацией
применение обновляет файлы с использованием атомарной замены файлов и восстановления в случае сбоя по возможности

Примечания по совместимости с устаревшей аутентификацией

Для статических учетных данных среда выполнения больше не зависит от устаревшего хранилища аутентификации в виде обычного текста.

Источник учетных данных среды выполнения — это разрешенный снимок в памяти.
Устаревшие статические записи api_key удаляются при обнаружении.
Поведение совместимости, связанное с OAuth, остается отдельным.

Примечание о веб-интерфейсе

Некоторые объединения SecretInput проще настроить в режиме raw-редактора, чем в режиме формы.

Связанные документы

CLI-команды: secrets
Детали контракта плана: Контракт плана применения секретов
Поверхность учетных данных: Поверхность учетных данных SecretRef
Настройка аутентификации: Аутентификация
Положение безопасности: Безопасность
Приоритет переменных окружения: Переменные окружения

Семантика учетных данных аутентификации Контракт плана применения секретов