OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Gateway

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

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

Модель выполнения

  • Секреты разрешаются в хранящийся в памяти снимок среды выполнения заранее при активации, а не отложенно в путях обработки запросов.
  • Запуск немедленно завершается ошибкой, если фактически активный 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 проверяются только на фактически активных поверхностях:

  • Включенные поверхности: неразрешенные ссылки блокируют запуск или перезагрузку.
  • Неактивные поверхности: неразрешенные ссылки не блокируют запуск или перезагрузку; для них выдается некритическая диагностика 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: "..." }

env

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}$

file

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

exec

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 для этого поставщика, чтобы обойти проверку.
Exec-провайдер
  • Запускает настроенный исполняемый файл по абсолютному пути напрямую, без оболочки.
  • По умолчанию 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": "<openai-api-key>" } } // 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.

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

Специальное руководство по 1Password, посвящённое сервисным аккаунтам, встроенному навыку агента и устранению неполадок, см. в разделе 1Password.

1Password CLI
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" },      },    },  },}
Bitwarden Secrets Manager (`bws`)

Используйте обёртку средства разрешения, чтобы сопоставлять идентификаторы 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
HashiCorp Vault CLI
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" },      },    },  },}
password-store (`pass`)

Используйте небольшую обёртку средства разрешения, чтобы напрямую сопоставлять идентификаторы 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 nodeconst { 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 --checkopenclaw secrets audit --allow-exec
sops
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.

Обязательное поведение и приоритет

  • Поле без ссылки: без изменений.
  • Поле со ссылкой: обязательно на активных поверхностях во время активации.
  • Если присутствуют и открытый текст, и ссылка, на поддерживаемых путях определения приоритета ссылка имеет приоритет.
  • Маркер редактирования __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

  • Настроить и применить SecretRef

    bash
    openclaw secrets configure --apply

  • Повторить аудит

    bash
    openclaw secrets audit --check

    • Не считайте миграцию завершённой, пока повторный аудит не будет пройден без замечаний. Если аудит по-прежнему сообщает о хранящихся значениях в открытом виде, риск доступа агента сохраняется, даже когда API среды выполнения возвращают отредактированные значения.

    Если во время configure вы сохраняете план вместо его применения, примените сохранённый план с помощью openclaw secrets apply --from <plan-path> до повторного аудита.

    secrets audit

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

    • Хранящиеся значения в открытом виде (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 configure

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

    • Сначала настраивает 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 <id>

    Действия по умолчанию при применении configure:

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

    Применение сохранённого плана:

    bash
    openclaw secrets apply --from /tmp/openclaw-secrets-plan.jsonopenclaw secrets apply --from /tmp/openclaw-secrets-plan.json --allow-execopenclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-runopenclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run --allow-exec

    Примечание об exec: пробный запуск пропускает проверки exec, если не задан --allow-exec; режим записи отклоняет планы, содержащие SecretRef или провайдеры exec, если не задан --allow-exec.

    Подробности строгого контракта целей и путей, а также точные правила отклонения см. в разделе Контракт плана применения секретов.

    Односторонняя политика безопасности

    Модель безопасности:

    • Перед режимом записи предварительная проверка должна завершиться успешно.
    • Активация среды выполнения проверяется до фиксации.
    • При применении файлы обновляются с помощью атомарной замены, а при сбое по возможности восстанавливаются.

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

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

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

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

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

    Связанные разделы

    Was this useful?
    On this page

    On this page