Контракт плану застосування секретів

​

Структура файлу плану

{
  version: 1,
  protocolVersion: 1,
  targets: [
    {
      type: "models.providers.apiKey",
      path: "models.providers.openai.apiKey",
      pathSegments: ["models", "providers", "openai", "apiKey"],
      providerId: "openai",
      ref: { source: "env", provider: "default", id: "OPENAI_API_KEY" },
    },
    {
      type: "auth-profiles.api_key.key",
      path: "profiles.openai:default.key",
      pathSegments: ["profiles", "openai:default", "key"],
      agentId: "main",
      ref: { source: "env", provider: "default", id: "OPENAI_API_KEY" },
    },
  ],
}

​

Додавання, оновлення та видалення провайдерів

• providerUpserts — об’єкт, ключами якого є псевдоніми провайдерів. Кожне значення є визначенням провайдера (тієї самої структури, яка приймається в secrets.providers.<alias> у openclaw.json, наприклад провайдер exec або file).
• providerDeletes — масив псевдонімів провайдерів, які потрібно видалити.

{
  version: 1,
  protocolVersion: 1,
  providerUpserts: {
    onepassword_anthropic: {
      source: "exec",
      command: "/usr/bin/op",
      args: ["read", "op://Vault/Anthropic/credential"],
    },
  },
  providerDeletes: ["legacy_unused_alias"],
  targets: [
    {
      type: "models.providers.apiKey",
      path: "models.providers.anthropic.apiKey",
      pathSegments: ["models", "providers", "anthropic", "apiKey"],
      providerId: "anthropic",
      ref: { source: "exec", provider: "onepassword_anthropic", id: "credential" },
    },
  ],
}

​

Підтримувана область цілей

​

Поведінка типів цілей

​

Правила перевірки шляхів

• type має бути розпізнаним типом цілі.
• path має бути непорожнім шляхом із компонентами, розділеними крапками.
• pathSegments можна не вказувати. Якщо його вказано, результат нормалізації має точно збігатися з path.
• Заборонені компоненти відхиляються: __proto__, prototype, constructor.
• Нормалізований шлях має відповідати зареєстрованій структурі шляху для типу цілі.
• Якщо задано providerId або accountId, значення має збігатися з ідентифікатором, закодованим у шляху.
• Цілі auth-profiles.json потребують agentId.
• Під час створення нового зіставлення auth-profiles.json укажіть authProfileProvider.

​

Поведінка в разі помилки

Invalid plan target path for models.providers.apiKey: models.providers.openai.baseUrl

​

Поведінка згоди для провайдера виконання

• --dry-run типово пропускає перевірки SecretRef типу exec.
• Плани, що містять SecretRef або провайдери типу exec, відхиляються в режимі запису, якщо не задано --allow-exec.
• Під час перевірки або застосування планів, що містять exec, передавайте --allow-exec як у команді пробного запуску, так і в команді запису.

​

Примітки щодо області виконання та аудиту

• Записи auth-profiles.json, що містять лише посилання (keyRef/tokenRef), включено до визначення облікових даних під час виконання та охоплення аудитом.
• secrets apply записує підтримувані цілі openclaw.json, підтримувані цілі auth-profiles.json і виконує три необов’язкові проходи очищення, кожен із яких типово ввімкнений: scrubEnv (видаляє перенесені відкриті значення з .env), scrubAuthProfilesForProviderTargets (очищає залишки відкритих значень і невикористаних посилань у auth-profiles.json для провайдерів, які щойно переніс план) та scrubLegacyAuthJson (видаляє перенесені записи api_key із застарілих сховищ auth.json). Щоб пропустити відповідний прохід, установіть у плані будь-який із параметрів options.scrubEnv, options.scrubAuthProfilesForProviderTargets або options.scrubLegacyAuthJson у значення false.

​

Перевірки оператора

# Перевірити план без запису
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run

# Потім застосувати насправді
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json

# Для планів, що містять exec, явно надайте згоду в обох режимах
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run --allow-exec
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --allow-exec

​

Пов’язана документація

• Керування секретами
• CLI secrets
• Область облікових даних SecretRef
• Довідник із конфігурації