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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Контракт SecretRef

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

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

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

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

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

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

Визначайте постачальників у 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,      },    },    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" } }}

Приклади інтеграції 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: {      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" },      },    },  },}

{  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 server

Env vars MCP server, налаштовані через plugins.entries.acpx.config.mcpServers, підтримують SecretInput. Це тримає API keys і токени поза конфігурацією у відкритому тексті:

{  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-template refs на кшталт ${MCP_SERVER_API_KEY} і об’єкти SecretRef розв’язуються під час активації Gateway перед запуском процесу MCP server. Як і з іншими поверхнями SecretRef, нерозв’язані refs блокують активацію лише тоді, коли plugin acpx фактично активний.

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

Core backend 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" },        },      },    },  },}

Поведінка runtime:

• OpenClaw розв’язує ці refs під час активації пісочниці, а не ліниво під час кожного SSH-виклику.
• Розв’язані значення записуються в тимчасові файли з обмежувальними дозволами та використовуються у згенерованій SSH-конфігурації.
• Якщо ефективний бекенд пісочниці не ssh, ці refs залишаються неактивними й не блокують запуск.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Сигнали погіршення та відновлення

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

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

• SECRETS_RELOADER_DEGRADED
• SECRETS_RELOADER_RECOVERED

Поведінка:

• Погіршений стан: runtime зберігає останній відомий справний snapshot.
• Відновлено: надсилається один раз після наступної успішної активації.
• Повторні помилки, коли система вже в погіршеному стані, журналюють попередження, але не засмічують події.
• Startup fail-fast не надсилає події погіршення, бо runtime ніколи не ставав активним.

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

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

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

Інші нотатки:

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

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

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

openclaw secrets audit --check

openclaw secrets configure

openclaw secrets audit --check

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

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

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

• preflight має завершитися успішно перед режимом запису
• runtime-активація перевіряється перед commit
• apply оновлює файли за допомогою атомарної заміни файлів і best-effort restore у разі помилки

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

Для статичних облікових даних runtime більше не залежить від застарілого відкритотекстового сховища auth.

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

Нотатка Web UI

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

Пов’язане

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