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

​

Модель середовища виконання

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

​

Впровадження під час вихідного передавання (сторожові значення)

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

​

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

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

​

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

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

​

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

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

​

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

• Посилання на середовище: перевіряє ім’я змінної середовища та підтверджує, що під час налаштування доступне непорожнє значення.
• Посилання постачальника (file або exec): перевіряє вибір постачальника, розв’язує id і перевіряє тип розв’язаного значення.
• Процес швидкого старту: якщо gateway.auth.token уже є SecretRef, початкове налаштування розв’язує його перед пробним запуском/ініціалізацією панелі керування (для посилань env, file і exec) за допомогою того самого шлюзу негайної відмови.

​

Контракт 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: {
      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": { "code": "NOT_FOUND" } }
}

​

API-ключі у файлах

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

​

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

{
  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 node
const { 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 }));
});

{
  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 --check
openclaw 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

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

​

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

​

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

​

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

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

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

​

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

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

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

​

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

• SECRETS_RELOADER_DEGRADED
• SECRETS_RELOADER_RECOVERED

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

​

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

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

​

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

openclaw secrets audit --check

openclaw secrets configure --apply

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

​

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

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

​

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

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

​

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

​

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

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