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

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.json
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --allow-exec
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run
openclaw 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 — поверхня облікових даних
• Контракт плану застосування секретів — подробиці контракту плану
• Безпека — позиція безпеки