Керування секретами

OpenClaw підтримує адитивні SecretRefs, щоб підтримувані облікові дані не потрібно було зберігати як відкритий текст у конфігурації.

Цілі та модель виконання

Секрети розв’язуються в знімок виконання в пам’яті.

• Розв’язання виконується завчасно під час активації, а не ліниво на шляхах запитів.
• Запуск швидко завершується з помилкою, коли фактично активний SecretRef не може бути розв’язаний.
• Перезавантаження використовує атомарну заміну: повний успіх або збереження останнього відомого справного знімка.
• Порушення політики SecretRef (наприклад, профілі автентифікації в режимі OAuth у поєднанні з введенням SecretRef) зупиняють активацію до заміни середовища виконання.
• Запити виконання читають лише з активного знімка в пам’яті.
• Після першої успішної активації/завантаження конфігурації шляхи коду виконання продовжують читати цей активний знімок у пам’яті, доки успішне перезавантаження не замінить його.
• Шляхи вихідної доставки також читають із цього активного знімка (наприклад, доставка відповідей/тредів Discord і надсилання дій Telegram); вони не розв’язують SecretRefs повторно під час кожного надсилання.

Це прибирає збої постачальника секретів із гарячих шляхів запитів.

Межа доступу агента

SecretRefs захищають облікові дані від збереження в підтримуваній конфігурації та згенерованих поверхнях моделей, але вони не є межею ізоляції процесу. Якщо облікові дані у відкритому тексті залишаються на диску в шляху, який агент може читати, агент може обійти редагування на рівні API, використовуючи файлові або shell-інструменти для перевірки цього файла.

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

• підтримувані облікові дані використовують SecretRefs замість значень у відкритому тексті
• застарілі залишки відкритого тексту очищено з openclaw.json, auth-profiles.json, .env і згенерованих файлів models.json
• openclaw secrets audit --check після міграції не виявляє проблем
• усі решта непідтримуваних або ротаційних облікових даних захищені ізоляцією операційної системи, ізоляцією контейнера або зовнішнім проксі облікових даних

Саме тому робочий процес audit/configure/apply є шлюзом міграції безпеки, а не просто зручним помічником.

Фільтрація активної поверхні

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

• Увімкнені поверхні: нерозв’язані посилання блокують запуск/перезавантаження.
• Неактивні поверхні: нерозв’язані посилання не блокують запуск/перезавантаження.
• Неактивні посилання видають нефатальні діагностичні повідомлення з кодом SECRETS_REF_IGNORED_INACTIVE_SURFACE.

Діагностика поверхні автентифікації Gateway

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

• active: SecretRef є частиною ефективної поверхні автентифікації та має розв’язатися.
• inactive: SecretRef ігнорується для цього середовища виконання, тому що перемагає інша поверхня автентифікації або тому що віддалену автентифікацію вимкнено/не активовано.

Ці записи журналюються з SECRETS_GATEWAY_AUTH_SURFACE і містять причину, використану політикою активної поверхні, тож ви можете побачити, чому облікові дані вважалися активними або неактивними.

Попередня перевірка посилань під час онбордингу

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

• Env refs: перевіряє ім’я змінної env і підтверджує, що непорожнє значення видиме під час налаштування.
• Provider refs (file або exec): перевіряє вибір постачальника, розв’язує id і перевіряє тип розв’язаного значення.
• Шлях повторного використання Quickstart: коли gateway.auth.token уже є SecretRef, онбординг розв’язує його перед bootstrap probe/dashboard (для посилань env, file і exec) за допомогою того самого fail-fast шлюзу.

Якщо перевірка не вдається, онбординг показує помилку й дає змогу повторити спробу.

Контракт SecretRef

Використовуйте одну форму об’єкта всюди:

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

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

"${OPENAI_API_KEY}""$OPENAI_API_KEY"

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

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

Конфігурація постачальника

Визначайте постачальників у secrets.providers:

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

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

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

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

API-ключі на основі файлів

Не розміщуйте рядки file:... у блоці env конфігурації. Блок env є літеральним і не перевизначає значення, тому file:... не розв’язується.

Натомість використовуйте файловий SecretRef у підтримуваному полі облікових даних:

{  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 pointer, наприклад "/providers/xai/apiKey".

Див. Поверхня облікових даних SecretRef для полів конфігурації, які приймають SecretRefs.

Приклади інтеграції exec

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

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

openclaw secrets audit --allow-exec

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

#!/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(`Failed to parse request: ${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 exited ${result.status}`).trim() };    }  }   process.stdout.write(JSON.stringify({ protocolVersion: 1, values, errors }));});

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

openclaw secrets audit --checkopenclaw secrets audit --allow-exec

{  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-ключам і токенам потрапляти в конфігурацію відкритим текстом:

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

Рядкові значення відкритим текстом і далі працюють. Посилання env-шаблонів на кшталт ${MCP_SERVER_API_KEY} і об’єкти SecretRef розв’язуються під час активації Gateway до запуску процесу MCP-сервера. Як і з іншими поверхнями SecretRef, нерозв’язані посилання блокують активацію лише тоді, коли Plugin acpx фактично активний.

Матеріал SSH-автентифікації sandbox

Основний бекенд sandbox ssh також підтримує SecretRefs для матеріалу SSH-автентифікації:

{  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 розв’язує ці посилання під час активації sandbox, а не ліниво під час кожного SSH-виклику.
• Розв’язані значення записуються до тимчасових файлів з обмежувальними дозволами й використовуються у згенерованій SSH-конфігурації.
• Якщо ефективний бекенд sandbox не ssh, ці посилання залишаються неактивними й не блокують запуск.

Підтримувана поверхня облікових даних

Канонічні підтримувані й непідтримувані облікові дані перелічено тут:

• Поверхня облікових даних SecretRef

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

• Поле без посилання: без змін.
• Поле з посиланням: обов’язкове на активних поверхнях під час активації.
• Якщо присутні і відкритий текст, і посилання, посилання має пріоритет на підтримуваних шляхах пріоритету.
• Сентинел редагування __OPENCLAW_REDACTED__ зарезервований для внутрішнього редагування/відновлення конфігурації та відхиляється як буквальні надіслані дані конфігурації.

Сигнали попереджень і аудиту:

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

Поведінка сумісності Google Chat:

• serviceAccountRef має пріоритет над serviceAccount відкритим текстом.
• Значення відкритим текстом ігнорується, коли встановлено сусіднє посилання.

Тригери активації

Активація секретів виконується під час:

• Запуску (попередня перевірка плюс остаточна активація)
• Шляху гарячого застосування перезавантаження конфігурації
• Шляху перевірки перезапуску після перезавантаження конфігурації
• Ручного перезавантаження через secrets.reload
• Попередньої перевірки Gateway config write RPC (config.set / config.apply / config.patch) для розв’язності SecretRef активної поверхні в надісланому конфігураційному payload до збереження змін

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

• Успіх атомарно замінює знімок.
• Помилка запуску перериває запуск Gateway.
• Помилка перезавантаження під час виконання зберігає останній відомий справний знімок.
• Помилка попередньої перевірки write-RPC відхиляє надіслану конфігурацію та залишає як конфігурацію на диску, так і активний знімок виконання без змін.
• Надання явного токена каналу для окремого виклику outbound helper/tool не запускає активацію SecretRef; точками активації залишаються запуск, перезавантаження та явний secrets.reload.

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

Коли активація під час перезавантаження завершується помилкою після справного стану, OpenClaw переходить у деградований стан секретів.

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

• SECRETS_RELOADER_DEGRADED
• SECRETS_RELOADER_RECOVERED

Поведінка:

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

Розв’язання шляхів команд

Шляхи команд можуть увімкнути підтримуване розв’язання SecretRef через snapshot RPC Gateway.

Є дві широкі моделі поведінки:

Інші примітки:

• Оновлення знімка після ротації секретів на бекенді обробляється командою openclaw secrets reload.
• Метод Gateway RPC, який використовують ці шляхи команд: secrets.resolve.

Робочий процес аудиту й налаштування

Типовий потік оператора:

openclaw secrets audit --check

openclaw secrets configure --apply

openclaw secrets audit --check

Не вважайте міграцію завершеною, доки повторний аудит не буде чистим. Якщо аудит досі повідомляє про відкриті текстові значення в стані спокою, ризик доступу агента ще присутній, навіть коли API середовища виконання повертають редаговані значення.

Якщо ви зберігаєте план замість застосування під час configure, застосуйте цей збережений план за допомогою openclaw secrets apply --from <plan-path> перед повторним аудитом.

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

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

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

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

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

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

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

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

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

Пов’язане

• Автентифікація — налаштування автентифікації
• CLI: secrets — команди CLI
• Змінні середовища — пріоритет середовища
• Поверхня облікових даних SecretRef — поверхня облікових даних
• Контракт плану застосування секретів — деталі контракту плану
• Безпека — стан безпеки