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

Необов’язкові помилки для окремих ідентифікаторів:

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" значенням SecretRef id є "value". Для mode: "json" використовуйте абсолютний вказівник JSON, наприклад "/providers/xai/apiKey".

Перелік полів, які приймають SecretRef, наведено в розділі Область облікових даних SecretRef.

Приклади інтеграції виконання

Спеціальний посібник із 1Password, що охоплює службові облікові записи, вбудовану навичку агента та усунення несправностей, див. у розділі 1Password.

CLI 1Password
json5
{  secrets: {    providers: {      onepassword_openai: {        source: "exec",        command: "/opt/homebrew/bin/op",        allowSymlinkCommand: true, // required for Homebrew symlinked binaries        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.
  • BWS_SERVER_URL установлено в середовищі під час використання власного екземпляра Bitwarden.
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. Використовуйте ключі, які відповідають контракту ідентифікатора SecretRef для виконання, наприклад openclaw/providers/openai/apiKey; ключі у стилі змінних середовища з підкресленнями відхиляються до запуску засобу визначення. Якщо запитаний ключ мають кілька видимих секретів Bitwarden, засіб визначення позначає цей ідентифікатор як неоднозначний і завершує його обробку помилкою замість припущення. Після оновлення конфігурації перевірте шлях засобу визначення:

bash
openclaw secrets audit --allow-exec
CLI HashiCorp Vault
json5
{  secrets: {    providers: {      vault_openai: {        source: "exec",        command: "/opt/homebrew/bin/vault",        allowSymlinkCommand: true, // required for Homebrew symlinked binaries        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. Збережіть її як виконуваний файл за абсолютним шляхом, який проходить перевірки шляхів провайдера виконання, наприклад /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 }));});

Потім налаштуйте провайдер виконання та спрямуйте 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. Після оновлення конфігурації перевірте статичний аудит і шлях засобу визначення виконання:

bash
openclaw secrets audit --checkopenclaw secrets audit --allow-exec
sops
json5
{  secrets: {    providers: {      sops_openai: {        source: "exec",        command: "/opt/homebrew/bin/sops",        allowSymlinkCommand: true, // required for Homebrew symlinked binaries        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>.

    аудит секретів

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

    • Значення у відкритому тексті в стані спокою (openclaw.json, auth-profiles.json, .env і згенерований agents/*/agent/models.json).
    • Залишки конфіденційних заголовків провайдера у відкритому тексті в згенерованих записах models.json.
    • Нерозв’язані посилання.
    • Затінення пріоритетністю (auth-profiles.json має пріоритет над посиланнями openclaw.json).
    • Застарілі залишки (auth.json, нагадування OAuth).

    Примітка щодо exec: за замовчуванням аудит пропускає перевірки можливості розв’язання exec SecretRef, щоб уникнути побічних ефектів команд. Використовуйте 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: попередня перевірка пропускає перевірки exec SecretRef, якщо не встановлено --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.
    застосування секретів

    Застосування збереженого плану:

    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; режим запису відхиляє плани, що містять exec SecretRef/провайдери, якщо не встановлено --allow-exec.

    Докладні відомості про суворий контракт цілі/шляху й точні правила відхилення наведено в розділі Контракт плану застосування секретів.

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

    Модель безпеки:

    • Попередня перевірка має завершитися успішно перед режимом запису.
    • Активація середовища виконання перевіряється перед фіксацією.
    • Застосування оновлює файли за допомогою атомарної заміни файлів і намагається відновити їх у разі помилки.

    Примітки щодо сумісності із застарілою автентифікацією

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

    • Джерелом облікових даних середовища виконання є розв’язаний знімок у пам’яті.
    • Застарілі статичні записи api_key видаляються під час виявлення.
    • Поведінка сумісності, пов’язана з OAuth, залишається окремою.

    Примітка щодо вебінтерфейсу

    Деякі об’єднання SecretInput простіше налаштовувати в режимі редактора необробленого тексту, ніж у режимі форми.

    Пов’язані матеріали

    Was this useful?
    On this page

    On this page