Контракт плана применения секретов

​

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

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

​

Поведение при ошибке

Недопустимый путь целевого объекта плана для models.providers.apiKey: models.providers.openai.baseUrl

​

Поведение согласия для exec-провайдеров

• --dry-run по умолчанию пропускает проверки exec 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
• Справочник по конфигурации