Vai al contenuto principale

​
Contratto del piano secrets apply

Questa pagina definisce il contratto rigoroso applicato da openclaw secrets apply. Se un target non corrisponde a queste regole, l’applicazione fallisce prima di modificare la configurazione.

​
Forma del file di piano

openclaw secrets apply --from <plan.json> si aspetta un array targets di target del piano: 
{
  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" },
    },
  ],
}

​
Ambito target supportato

I target del piano sono accettati per i percorsi delle credenziali supportati in:

​
Comportamento del tipo target

Regola generale:
  • target.type deve essere riconosciuto e deve corrispondere alla forma normalizzata di target.path.
Gli alias di compatibilità restano accettati per i piani esistenti:
  • models.providers.apiKey
  • skills.entries.apiKey
  • channels.googlechat.serviceAccount

​
Regole di validazione del percorso

Ogni target viene validato con tutti i controlli seguenti:
  • type deve essere un tipo target riconosciuto.
  • path deve essere un percorso dot non vuoto.
  • pathSegments può essere omesso. Se fornito, deve normalizzarsi esattamente nello stesso percorso di path.
  • I segmenti vietati vengono rifiutati: __proto__, prototype, constructor.
  • Il percorso normalizzato deve corrispondere alla forma del percorso registrata per il tipo target.
  • Se providerId o accountId è impostato, deve corrispondere all’id codificato nel percorso.
  • I target auth-profiles.json richiedono agentId.
  • Quando crei una nuova mappatura auth-profiles.json, includi authProfileProvider.

​
Comportamento in caso di errore

Se un target fallisce la validazione, apply termina con un errore come: 
Invalid plan target path for models.providers.apiKey: models.providers.openai.baseUrl
Nessuna scrittura viene confermata per un piano non valido.

​
Comportamento del consenso per il provider exec

  • --dry-run salta per impostazione predefinita i controlli SecretRef exec.
  • I piani che contengono SecretRef/provider exec vengono rifiutati in modalità scrittura a meno che non sia impostato --allow-exec.
  • Quando convalidi/applichi piani che contengono exec, passa --allow-exec sia nei comandi dry-run sia in quelli di scrittura.

​
Note su runtime e ambito di audit

  • Le voci auth-profiles.json solo-ref (keyRef/tokenRef) sono incluse nella risoluzione runtime e nella copertura di audit.
  • secrets apply scrive target openclaw.json supportati, target auth-profiles.json supportati e target opzionali di pulizia.

​
Controlli per l’operatore

# Convalida il piano senza scritture
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run

# Poi applicalo davvero
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json

# Per i piani che contengono exec, effettua esplicitamente l'opt-in in entrambe le modalità
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --dry-run --allow-exec
openclaw secrets apply --from /tmp/openclaw-secrets-plan.json --allow-exec
Se apply fallisce con un messaggio di percorso target non valido, rigenera il piano con openclaw secrets configure oppure correggi il percorso target in una forma supportata indicata sopra.

​
Documentazione correlata