Valida y aplica planes de OpenClaw: Guía de contrato

Gestionar secretos puede ser un dolor de cabeza si no tienes claro qué se va a modificar exactamente. Para evitar errores inesperados y configuraciones corruptas, openclaw secrets apply utiliza un contrato estricto que garantiza que todo sea válido antes de realizar cualquier cambio en tu sistema.

Esta página define el contrato que aplica el comando openclaw secrets apply. Si un destino no cumple con estas reglas, el proceso fallará antes de modificar cualquier configuración.

Estructura del archivo de plan

El comando openclaw secrets apply --from <plan.json> espera un array targets con los 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 los destinos soportados

Se aceptan destinos de plan para las rutas de credenciales soportadas en:

• SecretRef Credential Surface

Comportamiento del tipo de destino

Como regla general:

• El campo target.type debe ser reconocido y debe coincidir con la forma de la ruta normalizada en target.path.

Se siguen aceptando alias de compatibilidad para planes existentes:

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

Reglas de validación de rutas

Cada destino se valida siguiendo todos estos puntos:

• El type debe ser un tipo de destino reconocido.
• El path debe ser una ruta de puntos (dot path) que no esté vacía.
• pathSegments se puede omitir. Si lo incluyes, debe normalizarse exactamente a la misma ruta que path.
• Se rechazan los segmentos prohibidos: __proto__, prototype, constructor.
• La ruta normalizada debe coincidir con la forma de la ruta registrada para ese tipo de destino.
• Si se define providerId o accountId, debe coincidir con el id codificado en la ruta.
• Los destinos de auth-profiles.json requieren un agentId.
• Al crear un nuevo mapeo en auth-profiles.json, asegúrate de incluir authProfileProvider.

Comportamiento en caso de error

Si un destino falla la validación, el comando apply termina con un error similar a este:

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

No se confirma ninguna escritura si el plan no es válido.

Notas sobre el tiempo de ejecución y el alcance de auditoría

• Las entradas de auth-profiles.json que solo son referencias (keyRef/tokenRef) se incluyen en la resolución en tiempo de ejecución y en la cobertura de auditoría.
• El comando secrets apply escribe los destinos soportados de openclaw.json, los destinos de auth-profiles.json y los destinos de limpieza (scrub) opcionales.

Comprobaciones del operador

Puedes validar tu plan sin realizar cambios reales usando el flag --dry-run:

# Validate plan without writes
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run

# Then apply for real
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json

Si el proceso falla con un mensaje de ruta de destino inválida, te recomiendo regenerar el plan con openclaw secrets configure o corregir la ruta del destino para que coincida con una de las formas soportadas mencionadas anteriormente.

Documentación relacionada

• Secrets Management
• CLI secrets
• SecretRef Credential Surface
• Configuration Reference

Pasos siguientes

• Secrets Management
• CLI secrets

AI Setup Assistant