Skip to main content

openclaw policy

openclaw policy è fornito dal Plugin Policy incluso. È un livello aziendale di conformità applicato alle impostazioni OpenClaw esistenti, non un secondo sistema di configurazione. I requisiti vengono definiti in policy.jsonc; OpenClaw osserva lo spazio di lavoro attivo come evidenza; Policy segnala le difformità tramite doctor --lint. Policy non impone le chiamate agli strumenti né riscrive il comportamento di runtime al momento della richiesta e non certifica gli archivi delle credenziali dei singoli agenti, come auth-profiles.json. Policy verifica i canali configurati, i server MCP, i provider di modelli, la postura SSRF della rete, l’accesso in ingresso e ai canali, l’esposizione del Gateway e la postura dei comandi dei Node, l’accesso degli agenti allo spazio di lavoro, la postura della sandbox, la postura di gestione dei dati, la postura dei provider di segreti e dei profili di autenticazione e i metadati degli strumenti soggetti a governance (TOOLS.md). Usalo quando uno spazio di lavoro necessita di una dichiarazione durevole e verificabile, ad esempio «Telegram non deve essere abilitato» o «gli strumenti soggetti a governance devono dichiarare i metadati relativi al rischio e al proprietario». Se serve solo un comportamento locale senza certificazione o rilevamento delle difformità, è sufficiente la normale configurazione.

Avvio rapido

Il Plugin rimane abilitato anche quando policy.jsonc è assente, così doctor può segnalare l’artefatto mancante anziché ignorare silenziosamente i controlli. Crea policy.jsonc manualmente; non viene generato dalle impostazioni correnti. Ogni sezione di primo livello è uno spazio dei nomi delle regole: un controllo viene eseguito solo quando contiene una regola concreta (le sezioni o le chiavi non supportate producono l’errore policy/policy-jsonc-invalid anziché essere ignorate silenziosamente). Esempio minimo che copre ogni sezione supportata:
Note trasversali non evidenti dalle tabelle delle regole riportate di seguito:
  • Omettere gateway.bind quando si negano i binding diversi da local loopback significa accettare il valore predefinito del runtime; imposta gateway.bind: "loopback" per una conformità rigorosa.
  • Per un agente di sola lettura, imposta la mode della sandbox su all o non-main nei valori predefiniti o nell’agente pertinente e workspaceAccess su none o ro. Una modalità sandbox assente o impostata su off non soddisfa una policy di sola lettura.
  • agents.workspace.denyTools accetta exec, process, write, edit, apply_patch. I gruppi di strumenti negati nella configurazione group:fs (modifica dei file) e group:runtime (shell/processi) soddisfano la postura equivalente.
  • I controlli delle approvazioni di esecuzione leggono l’artefatto attivo exec-approvals.json solo quando è presente una regola execApprovals; un artefatto assente o non valido costituisce un’evidenza non osservabile, non un esito positivo sintetico.
  • Le evidenze relative ai segreti e ai profili di autenticazione registrano solo la postura del provider o dell’origine e i metadati SecretRef, mai i valori non elaborati. Policy non legge né certifica gli archivi delle credenziali dei singoli agenti, come auth-profiles.json.
  • Le evidenze sulla gestione dei dati riguardano solo la postura a livello di configurazione (modalità di oscuramento, opzione di acquisizione della telemetria, modalità di manutenzione delle sessioni, impostazione di indicizzazione delle trascrizioni). Non esaminano registri, esportazioni della telemetria, trascrizioni o file di memoria e un risultato senza problemi non dimostra che non contengano dati personali o segreti.

Riferimento delle regole di Policy

Ogni regola seguente è facoltativa; un controllo viene eseguito solo quando la regola è presente. Lo stato osservato corrisponde alla configurazione OpenClaw esistente o ai metadati dello spazio di lavoro.

Sovrapposizioni con ambito

Usa scopes.<scopeName> quando agenti o canali specifici richiedono una policy più rigorosa rispetto alla baseline di primo livello. Il nome dell’ambito è solo un’etichetta; la corrispondenza usa il selettore all’interno dell’ambito. Le sovrapposizioni sono additive: la regola globale continua a essere eseguita e quella con ambito può aggiungere un proprio rilievo sulla stessa evidenza. Se una voce agentIds non è presente in agents.list[], OpenClaw valuta la regola con ambito rispetto alla postura globale o predefinita ereditata per quell’ID agente di runtime, anziché ignorarla.
Lo stesso agente può comparire in più ambiti se ciascun ambito governa un campo diverso, come nell’esempio precedente. Un campo con ambito ripetuto per lo stesso agente deve essere altrettanto o più restrittivo; una dichiarazione duplicata più permissiva viene rifiutata (gli elenchi di elementi consentiti devono essere sottoinsiemi, quelli di elementi negati devono essere sovrainsiemi e i valori booleani obbligatori sono fissi). Le regole sulla postura dei container (sandbox.containers.*) vengono verificate solo rispetto alle evidenze che il backend sandbox dell’agente corrispondente può esporre. Se un backend non può osservare una regola che hai abilitato per esso, Policy segnala policy/sandbox-container-posture-unobservable anziché considerarla soddisfatta; limita le regole dei container agli ambiti dei gruppi di agenti che usano un backend in grado di esporle. ingress.session.requireDmScope al primo livello rimane globale; session.dmScope non è un’evidenza attribuibile a un canale, quindi non può avere un ambito definito tramite channelIds. Ogni ambito presente in policy.jsonc deve essere valido e applicabile.

Canali

Server MCP

Provider di modelli

Rete

Accesso in ingresso e ai canali

Gateway

gateway.nodes.denyCommands è una regola di sovrainsieme delle negazioni esatta e con distinzione tra maiuscole e minuscole. Utilizzarla quando i criteri devono dimostrare che i comandi privilegiati dei nodi sono esplicitamente negati dalla configurazione di OpenClaw. Una distribuzione che consente intenzionalmente un comando privilegiato del nodo deve aggiornare policy.jsonc dopo la revisione, anziché affidarsi esclusivamente a gateway.nodes.allowCommands.

Area di lavoro dell’agente

Configurazione di sicurezza della sandbox

I criteri considerano l’assenza di sandbox.mode come il valore predefinito implicito off; pertanto, sandbox.requireMode segnala una sandbox nuova o non configurata come esterna a un elenco di valori consentiti quale ["all"].

Gestione dei dati

Segreti

Approvazioni dell’esecuzione

I controlli delle approvazioni dell’esecuzione leggono l’artefatto di runtime exec-approvals.json: ~/.openclaw/exec-approvals.json per impostazione predefinita oppure $OPENCLAW_STATE_DIR/exec-approvals.json quando è impostato OPENCLAW_STATE_DIR. Le regole di configurazione in execApprovals.defaults.* o execApprovals.agents.* richiedono evidenze leggibili nell’artefatto; un artefatto mancante o non valido viene segnalato come evidenza non osservabile, anziché essere accettato secondo il principio del massimo sforzo. Una volta leggibile, i campi omessi ereditano i valori predefiniti del runtime: se defaults.security è assente, il valore è full, mentre l’impostazione di sicurezza assente per un agente eredita tale valore predefinito. Le evidenze includono defaults, agents.*, agents.*.allowlist[].pattern, l’eventuale argPattern, la configurazione effettiva di autoAllowSkills e l’origine della voce, ma mai il percorso/token del socket, commandText, lastUsedCommand, i percorsi risolti o i timestamp. Esempio: richiedere l’artefatto delle approvazioni, negare impostazioni predefinite permissive e consentire solo configurazioni delle approvazioni dell’esecuzione sottoposte a revisione per gli agenti selezionati.

Profili di autenticazione

Metadati degli strumenti

Configurazione degli strumenti

Eseguire i controlli

Durante la creazione, eseguire esclusivamente i controlli dei criteri:
policy check esegue solo l’insieme dei controlli dei criteri e produce evidenze, risultati e hash di attestazione. Gli stessi risultati vengono visualizzati anche in openclaw doctor --lint quando il Plugin Policy è abilitato. Confrontare un file dei criteri dell’operatore con una baseline creata:
policy compare verifica la sintassi del file dei criteri rispetto alla sintassi del file dei criteri; non esamina lo stato di runtime, le evidenze, le credenziali o i segreti. Usa gli stessi metadati delle regole che disciplinano le sovrapposizioni con ambito: le allowlist devono rimanere uguali o più restrittive, le denylist devono rimanere uguali o più ampie, i valori booleani obbligatori devono mantenere il proprio valore, le stringhe ordinate possono spostarsi solo verso l’estremità più restrittiva dell’ordine configurato e gli elenchi esatti devono corrispondere. La baseline può essere un criterio creato dall’organizzazione; il criterio verificato può aggiungere valori più restrittivi o regole aggiuntive. Una regola di primo livello verificata può soddisfare una regola della baseline con ambito quando è altrettanto o più restrittiva. I nomi degli ambiti non devono necessariamente coincidere tra i file; il confronto è basato sul selettore (agentIds/channelIds) e sul campo. Confronto senza risultati (--json):
L’output senza risultati di policy check --json include hash stabili che un operatore o supervisore può registrare:

Configurare i criteri

La configurazione dei criteri si trova in plugins.entries.policy.config.
Impostare plugins.entries.policy.config.enabled su false per disabilitare i controlli dei criteri per un’area di lavoro lasciando installato il Plugin.

Accettare lo stato dei criteri

Esempio di output JSON:
attestation.policy.hash identifica l’artefatto delle regole creato. evidence registra lo stato osservato di OpenClaw utilizzato dai controlli e workspace.hash identifica il relativo payload di evidenze. findingsHash identifica l’insieme esatto dei risultati. checkedAt registra il momento in cui è stato eseguito il controllo. attestationHash identifica l’attestazione stabile (hash dei criteri, hash delle evidenze, hash dei risultati e stato senza/con risultati) ed esclude deliberatamente checkedAt, in modo che lo stesso stato dei criteri produca sempre lo stesso hash di attestazione. Insieme, questi quattro valori costituiscono la tupla di audit per un controllo dei criteri. Se un Gateway o un supervisore usa i criteri per bloccare, approvare o annotare un’azione di runtime, deve registrare l’hash di attestazione dell’ultimo controllo senza risultati. checkedAt rimane nell’output JSON per i log di audit, ma non fa parte dell’hash stabile. Ciclo di vita per l’accettazione dello stato dei criteri:
  1. Creare o revisionare policy.jsonc.
  2. Eseguire openclaw policy check --json.
  3. Se non vengono rilevati risultati, registrare attestation.policy.hash come expectedHash.
  4. Registrare attestation.attestationHash come expectedAttestationHash.
  5. Eseguire nuovamente openclaw doctor --lint nella CI o nei controlli di rilascio.
Se le regole dei criteri cambiano intenzionalmente, aggiorna entrambi gli hash accettati a partire da un controllo pulito. Se cambiano solo le impostazioni dell’area di lavoro (i criteri restano invariati), in genere cambia solo expectedAttestationHash. L’abilitazione o l’aggiornamento delle regole agents.workspace aggiunge le evidenze agentWorkspace all’hash dell’area di lavoro e all’hash di attestazione; esamina le nuove evidenze e aggiorna gli hash di attestazione accettati dopo l’abilitazione. L’abilitazione o l’aggiornamento delle regole sull’assetto degli strumenti aggiunge allo stesso modo le evidenze toolPosture. openclaw policy watch riesegue il controllo e segnala quando le evidenze correnti non corrispondono più a expectedAttestationHash:
Usa --once nella CI o negli script che richiedono una singola valutazione delle variazioni. Senza --once, per impostazione predefinita esegue il polling ogni due secondi; usa --interval-ms per modificare l’intervallo.

Risultati

Un risultato può includere sia target (l’elemento osservato nell’area di lavoro che non è conforme) sia requirement (la regola definita che ha determinato il risultato). Attualmente entrambi sono stringhe di indirizzo oc://, ma i nomi dei campi descrivono il ruolo nei criteri anziché il formato dell’indirizzo. Esempi di risultati:

Riparazione

doctor --lint e policy check sono di sola lettura. doctor --fix modifica le impostazioni dell’area di lavoro gestite dai criteri solo quando workspaceRepairs è esplicitamente abilitato; in caso contrario, i controlli indicano cosa riparerebbero e lasciano invariate le impostazioni. In questa versione, la riparazione può disabilitare i canali vietati da channels.denyRules e applicare le riparazioni automatiche restrittive elencate di seguito. Abilita workspaceRepairs solo dopo aver esaminato il file dei criteri, perché una regola valida può modificare la configurazione dell’area di lavoro:
  • impostare tools.elevated.enabled=false quando un criterio globale vieta gli strumenti con privilegi elevati
  • aggiungere gli ID mancanti degli strumenti che devono essere vietati a tools.deny o agents.list[].tools.deny quando i criteri richiedono che tali strumenti siano vietati
  • impostare su false le opzioni non sicure di gateway.controlUi.*
  • impostare gateway.mode=local quando i criteri vietano la modalità Gateway remota
  • impostare su false i percorsi segnalati gateway.http.endpoints.*.enabled quando i criteri vietano gli endpoint dell’API HTTP del Gateway
  • impostare su allowlist i percorsi groupPolicy segnalati per l’ingresso dei canali quando i criteri vietano l’ingresso aperto nei gruppi
  • impostare su true i percorsi requireMention segnalati per l’ingresso dei canali quando i criteri richiedono le menzioni nei gruppi
  • impostare logging.redactSensitive=tools quando i criteri richiedono l’oscuramento dei dati sensibili nei log
  • impostare diagnostics.otel.captureContent=false, oppure diagnostics.otel.captureContent.enabled=false per le impostazioni di acquisizione della telemetria in forma di oggetto, quando i criteri vietano l’acquisizione del contenuto della telemetria
Le riparazioni con ambito limitato degli strumenti con privilegi elevati sono solo di rilevamento. Anche le riparazioni con ambito limitato relative alla gestione dei dati vengono ignorate quando il rilievo segnala una configurazione condivisa dei log o della telemetria, perché la modifica dell’impostazione condivisa avrebbe effetto su elementi ulteriori rispetto alla destinazione dei criteri con ambito limitato. Le riparazioni con ambito limitato dei divieti obbligatori vengono ignorate quando il rilievo segnala il valore radice ereditato tools.deny, perché l’aggiunta dello strumento richiesto alla configurazione radice avrebbe effetto su elementi ulteriori rispetto alla destinazione dei criteri con ambito limitato. Le riparazioni dei divieti obbligatori locali all’agente possono aggiornare il percorso segnalato agents.list[].tools.deny. Le riparazioni con ambito limitato dell’ingresso dei canali vengono ignorate quando il rilievo segnala channels.defaults.* ereditato, perché la modifica dell’impostazione predefinita condivisa del canale avrebbe effetto su elementi ulteriori rispetto alla destinazione dei criteri con ambito limitato. I rilievi relativi all’elenco consentito per il recupero di URL HTTP del Gateway rimangono manuali, perché la riparazione automatica non può scegliere i valori corretti dell’elenco di URL consentiti per l’endpoint. I rilievi relativi al binding del Gateway e ai comandi del Node continuano a richiedere una revisione. Quando policy/gateway-non-loopback-bind o policy/gateway-node-command-denied possono essere associati a un percorso di configurazione, doctor --fix segnala la modifica proposta di gateway.bind o gateway.nodes.denyCommands come indicazione di anteprima ignorata. Non applica la modifica e il rilievo non viene considerato riparato finché un operatore non esamina e aggiorna la configurazione o i criteri.

Codici di uscita

Contenuti correlati