Contrato del plan de Secrets Apply

Esta página define el contrato estricto que aplica openclaw secrets apply.

Si un destino no coincide con estas reglas, apply falla antes de modificar la configuración.

Formato del archivo de plan

openclaw secrets apply --from <plan.json> espera un array targets de destinos del plan:

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

Alcance de destinos soportado

Los destinos del plan se aceptan para rutas de credenciales soportadas en:

Superficie de credenciales SecretRef

Comportamiento del tipo de destino

Regla general:

target.type debe ser reconocido y debe coincidir con la forma normalizada de target.path.

Los alias de compatibilidad siguen aceptándose para planes existentes:

models.providers.apiKey
skills.entries.apiKey
channels.googlechat.serviceAccount

Reglas de validación de rutas

Cada destino se valida con todo lo siguiente:

type debe ser un tipo de destino reconocido.
path debe ser una ruta con puntos no vacía.
pathSegments puede omitirse. Si se proporciona, debe normalizarse exactamente a la misma ruta que path.
Los segmentos prohibidos se rechazan: __proto__, prototype, constructor.
La ruta normalizada debe coincidir con la forma registrada para el tipo de destino.
Si providerId o accountId está establecido, debe coincidir con el id codificado en la ruta.
Los destinos de auth-profiles.json requieren agentId.
Al crear un nuevo mapeo en auth-profiles.json, incluye authProfileProvider.

Comportamiento en caso de fallo

Si un destino falla en la validación, apply sale con un error como:

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

No se confirman escrituras para un plan inválido.

Notas de alcance de runtime y auditoría

Las entradas de auth-profiles.json solo con ref (keyRef/tokenRef) se incluyen en la resolución de runtime y la cobertura de auditoría.
secrets apply escribe destinos soportados de openclaw.json, destinos soportados de auth-profiles.json y destinos opcionales de limpieza.

Verificaciones del operador

# Validar plan sin escrituras
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run

# Luego aplicar de verdad
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json

Si apply falla con un mensaje de ruta de destino inválida, regenera el plan con openclaw secrets configure o corrige la ruta del destino a una forma soportada de las anteriores.