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
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:
- Omettere
gateway.bindquando si negano i binding diversi da local loopback significa accettare il valore predefinito del runtime; impostagateway.bind: "loopback"per una conformità rigorosa. - Per un agente di sola lettura, imposta la
modedella sandbox suallonon-mainnei valori predefiniti o nell’agente pertinente eworkspaceAccesssunoneoro. Una modalità sandbox assente o impostata suoffnon soddisfa una policy di sola lettura. agents.workspace.denyToolsaccettaexec,process,write,edit,apply_patch. I gruppi di strumenti negati nella configurazionegroup:fs(modifica dei file) egroup:runtime(shell/processi) soddisfano la postura equivalente.- I controlli delle approvazioni di esecuzione leggono l’artefatto attivo
exec-approvals.jsonsolo quando è presente una regolaexecApprovals; 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
Usascopes.<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.
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 runtimeexec-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):
policy check --json include hash stabili che un operatore o
supervisore può registrare:
Configurare i criteri
La configurazione dei criteri si trova inplugins.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:
- Creare o revisionare
policy.jsonc. - Eseguire
openclaw policy check --json. - Se non vengono rilevati risultati, registrare
attestation.policy.hashcomeexpectedHash. - Registrare
attestation.attestationHashcomeexpectedAttestationHash. - Eseguire nuovamente
openclaw doctor --lintnella CI o nei controlli di rilascio.
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:
--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=falsequando un criterio globale vieta gli strumenti con privilegi elevati - aggiungere gli ID mancanti degli strumenti che devono essere vietati a
tools.denyoagents.list[].tools.denyquando i criteri richiedono che tali strumenti siano vietati - impostare su
falsele opzioni non sicure digateway.controlUi.* - impostare
gateway.mode=localquando i criteri vietano la modalità Gateway remota - impostare su
falsei percorsi segnalatigateway.http.endpoints.*.enabledquando i criteri vietano gli endpoint dell’API HTTP del Gateway - impostare su
allowlisti percorsigroupPolicysegnalati per l’ingresso dei canali quando i criteri vietano l’ingresso aperto nei gruppi - impostare su
truei percorsirequireMentionsegnalati per l’ingresso dei canali quando i criteri richiedono le menzioni nei gruppi - impostare
logging.redactSensitive=toolsquando i criteri richiedono l’oscuramento dei dati sensibili nei log - impostare
diagnostics.otel.captureContent=false, oppurediagnostics.otel.captureContent.enabled=falseper le impostazioni di acquisizione della telemetria in forma di oggetto, quando i criteri vietano l’acquisizione del contenuto della telemetria
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.