`openclaw policy`

openclaw policy è fornito dal Plugin Policy incluso. Policy è un livello di conformità enterprise sopra le impostazioni OpenClaw esistenti. Non aggiunge un secondo sistema di configurazione. policy.jsonc definisce i requisiti redatti, OpenClaw osserva l’area di lavoro attiva come evidenza e i controlli di integrità delle policy segnalano le deviazioni tramite doctor --lint. Il segnale finale di conformità è un’esecuzione pulita di doctor --lint; policy contribuisce con rilevamenti a quella superficie di lint condivisa invece di creare un gate di integrità separato. Policy attualmente gestisce canali configurati, server MCP, provider di modelli, postura SSRF di rete, postura di accesso ingress/canale, postura di esposizione del Gateway, postura dell’area di lavoro dell’agente, postura di gestione dei dati, postura del provider di segreti/profilo auth della configurazione OpenClaw e dichiarazioni degli strumenti governati. Per esempio, l’IT o un operatore dell’area di lavoro può registrare che Telegram non è un provider di canale approvato, limitare server MCP e riferimenti di modello alle voci approvate, richiedere che l’accesso fetch/browser a reti private rimanga disabilitato, richiedere che l’isolamento delle sessioni di messaggi diretti e la postura di ingress del canale restino entro limiti revisionati, richiedere che bind/auth/esposizione HTTP del Gateway restino entro limiti revisionati, richiedere che l’accesso all’area di lavoro dell’agente e i deny degli strumenti restino in una postura revisionata, richiedere che i SecretRef della configurazione OpenClaw usino provider gestiti, richiedere che i profili auth di configurazione portino metadati di provider/modalità, richiedere che gli strumenti governati portino metadati di rischio e sensibilità, richiedere la redazione del logging sensibile, negare l’acquisizione dei contenuti di telemetria, richiedere la manutenzione della conservazione delle sessioni, negare l’indicizzazione in memoria delle trascrizioni di sessione, quindi usare doctor --lint come gate di conformità condiviso. Usa policy quando un’area di lavoro richiede una dichiarazione durevole come “questi canali non devono essere abilitati” o “gli strumenti governati devono dichiarare metadati di approvazione” e un modo ripetibile per dimostrare che OpenClaw è ancora conforme a quella dichiarazione. Usa solo la configurazione regolare e la documentazione dell’area di lavoro quando ti serve soltanto il comportamento locale e non ti servono rilevamenti di policy o output di attestazione.

Avvio rapido

Abilita il Plugin Policy incluso prima del primo utilizzo:

openclaw plugins enable policy

Quando policy è abilitato, doctor può caricare i controlli di integrità delle policy senza attivare Plugin arbitrari. Il Plugin resta abilitato se policy.jsonc manca, così doctor può segnalare l’artefatto mancante. Policy è redatto, non generato dalle impostazioni correnti dell’utente. Una policy minima per canali, server MCP, provider di modelli, postura di rete, accesso ingress/canale, esposizione Gateway, postura dell’area di lavoro dell’agente, postura del runtime sandbox configurato, postura di gestione dei dati OpenClaw, postura del provider di segreti/profilo auth della configurazione, postura del file di approvazione exec e metadati degli strumenti ha questo aspetto:

{
  "channels": {
    "denyRules": [
      {
        "id": "no-telegram",
        "when": { "provider": "telegram" },
        "reason": "Telegram is not approved for this workspace.",
      },
    ],
  },
  "mcp": {
    "servers": {
      "allow": ["docs"],
      "deny": ["untrusted"],
    },
  },
  "models": {
    "providers": {
      "allow": ["openai", "anthropic"],
      "deny": ["openrouter"],
    },
  },
  "network": {
    "privateNetwork": {
      "allow": false,
    },
  },
  "ingress": {
    "session": {
      "requireDmScope": "per-channel-peer",
    },
    "channels": {
      "allowDmPolicies": ["pairing", "allowlist", "disabled"],
      "denyOpenGroups": true,
      "requireMentionInGroups": true,
    },
  },
  "gateway": {
    "exposure": {
      "allowNonLoopbackBind": false,
      "allowTailscaleFunnel": false,
    },
    "auth": {
      "requireAuth": true,
      "requireExplicitRateLimit": true,
    },
    "controlUi": {
      "allowInsecure": false,
    },
    "remote": {
      "allow": false,
    },
    "http": {
      "denyEndpoints": ["chatCompletions", "responses"],
      "requireUrlAllowlists": true,
    },
  },
  "agents": {
    "workspace": {
      "allowedAccess": ["none", "ro"],
      "denyTools": ["exec", "process", "write", "edit", "apply_patch"],
    },
  },
  "dataHandling": {
    "sensitiveLogging": {
      "requireRedaction": true,
    },
    "telemetry": {
      "denyContentCapture": true,
    },
    "retention": {
      "requireSessionMaintenance": true,
    },
    "memory": {
      "denySessionTranscriptIndexing": true,
    },
  },
  "secrets": {
    "requireManagedProviders": true,
    "denySources": ["exec"],
    "allowInsecureProviders": false,
  },
  "auth": {
    "profiles": {
      "requireMetadata": ["provider", "mode"],
      "allowModes": ["api_key", "token"],
    },
  },
  "execApprovals": {
    "requireFile": true,
    "defaults": { "allowSecurity": ["deny"] },
    "agents": {
      "allowSecurity": ["deny", "allowlist"],
      "allowAutoAllowSkills": false,
      "allowlist": { "expected": ["deploy", "status"] },
    },
  },
  "tools": {
    "requireMetadata": ["risk", "sensitivity", "owner"],
    "profiles": {
      "allow": ["messaging", "minimal"],
    },
    "fs": {
      "requireWorkspaceOnly": true,
    },
    "exec": {
      "allowSecurity": ["deny", "allowlist"],
      "requireAsk": ["always"],
      "allowHosts": ["sandbox"],
    },
    "elevated": {
      "allow": false,
    },
    "denyTools": ["group:runtime", "group:fs"],
  },
}

Le regole sono l’autorità. Un blocco di categoria è solo uno spazio dei nomi; i controlli vengono eseguiti quando è presente una regola concreta. OpenClaw legge le impostazioni correnti channels.*, mcp.servers.*, models.providers.*, i riferimenti di modello agente selezionati, le impostazioni SSRF di rete, l’ambito delle sessioni di messaggi diretti, la policy DM del canale, la policy di gruppo del canale, i gate di menzione canale/gruppo, la postura bind/auth/Control UI/Tailscale/remote/HTTP del Gateway, la postura di accesso all’area di lavoro sandbox agente della configurazione OpenClaw e di deny degli strumenti, la postura della configurazione di gestione dei dati, la provenienza del provider di segreti e dei SecretRef della configurazione, i metadati dei profili auth di configurazione, la postura degli strumenti globali/per agente configurata e le dichiarazioni TOOLS.md come evidenza, quindi segnala lo stato osservato che non è conforme. Se una policy nega i bind Gateway non-loopback, ometti gateway.bind solo quando sei disposto a revisionare il valore predefinito del runtime; imposta gateway.bind=loopback per una conformità di configurazione rigorosa. Per la postura agente in sola lettura, configura la modalità sandbox sui default applicabili o sull’agente e imposta workspaceAccess a none o ro; una modalità sandbox omessa o off non soddisfa una policy in sola lettura/no-write. agents.workspace.denyTools supporta exec, process, write, edit e apply_patch; la configurazione OpenClaw group:fs copre gli strumenti di mutazione dei file e group:runtime copre gli strumenti shell/processo. La policy di postura degli strumenti osserva tools.profile, tools.allow, tools.alsoAllow, tools.deny, tools.fs.workspaceOnly, tools.exec.security, tools.exec.ask, tools.exec.host, tools.elevated.enabled e gli stessi override per agente agents.list[].tools.*. La policy di approvazione exec legge l’artefatto di prodotto denominato exec-approvals.json solo quando è presente una regola execApprovals; l’evidenza registra default, postura per agente e pattern allowlist senza token socket o testo dell’ultimo comando usato. Policy non applica le chiamate agli strumenti a runtime. L’evidenza dei segreti registra la postura provider/source e i metadati SecretRef, mai i valori grezzi dei segreti. Policy non legge né attesta archivi di credenziali per agente come auth-profiles.json; questi archivi restano di proprietà dei flussi auth e credenziali esistenti. L’evidenza di gestione dei dati è solo postura a livello di configurazione: controlla la modalità di redazione configurata, i toggle di acquisizione contenuti di telemetria, la modalità di manutenzione delle sessioni e le impostazioni di indicizzazione in memoria delle trascrizioni di sessione. Non ispeziona log grezzi, export di telemetria, contenuti di trascrizioni, file di memoria, né dimostra che non esistano dati personali o segreti.

Riferimento alle regole di policy

Ogni campo di policy qui sotto è facoltativo. Un controllo viene eseguito solo quando la regola corrispondente è presente in policy.jsonc. Lo stato osservato è la configurazione OpenClaw esistente o i metadati dell’area di lavoro; policy segnala le deviazioni ma non riscrive il comportamento del runtime a meno che un percorso di riparazione sia esplicitamente disponibile e abilitato. I file di policy sono rigorosi: sezioni o chiavi di regola non supportate vengono segnalate come policy/policy-jsonc-invalid invece di essere ignorate. Gli overlay di policy mantengono globali le regole ampie di primo livello, poi consentono ai blocchi di ambito denominati di aggiungere sezioni di policy normali più rigorose per selettori espliciti. Il nome di un ambito è solo un contenitore descrittivo; la corrispondenza usa i valori dei selettori dentro l’ambito. L’overlay è additivo: le dichiarazioni globali vengono comunque eseguite e una dichiarazione con ambito può emettere il proprio rilevamento sulla stessa configurazione osservata.

Overlay con ambito

Usa scopes.<scopeName> quando un insieme di agenti o canali richiede una policy più rigorosa rispetto alla baseline di primo livello. Le sezioni con ambito agente usano agentIds, che supporta tools.*, agents.workspace.*, sandbox.*, dataHandling.memory.* e execApprovals.*. L’ingress con ambito canale usa channelIds, che supporta ingress.channels.*. Le sezioni non supportate vengono rifiutate invece di essere ignorate. Se una voce agentIds non è presente in agents.list[], OpenClaw valuta la regola con ambito rispetto alla postura globale/default ereditata per quell’id agente runtime.

{
  "tools": {
    "exec": {
      "allowHosts": ["sandbox", "node"],
    },
  },
  "sandbox": {
    "requireMode": ["all", "non-main"],
  },
  "scopes": {
    "release-workspace": {
      "agentIds": ["release-agent", "review-agent"],
      "agents": {
        "workspace": {
          "allowedAccess": ["none", "ro"],
        },
      },
    },
    "release-lockdown": {
      "agentIds": ["release-agent"],
      "tools": {
        "exec": {
          "allowHosts": ["sandbox"],
          "allowSecurity": ["deny", "allowlist"],
          "requireAsk": ["always"],
        },
        "denyTools": ["exec", "process", "write", "edit", "apply_patch"],
      },
      "sandbox": {
        "requireMode": ["all"],
        "allowBackends": ["docker"],
      },
      "dataHandling": {
        "memory": {
          "denySessionTranscriptIndexing": true,
        },
      },
    },
    "shell-sandbox": {
      "agentIds": ["shell-agent"],
      "sandbox": {
        "allowBackends": ["openshell"],
        "containers": {
          "requireReadOnlyMounts": false,
        },
      },
    },
    "telegram-ingress": {
      "channelIds": ["telegram"],
      "ingress": {
        "channels": {
          "allowDmPolicies": ["pairing"],
          "denyOpenGroups": true,
          "requireMentionInGroups": true,
        },
      },
    },
  },
}

Lo stesso agente può apparire in più ambiti quando ogni ambito governa campi diversi, come mostrato sopra. Un campo con ambito ripetuto per lo stesso agente deve essere ugualmente o più restrittivo secondo i metadati di policy; le dichiarazioni duplicate più deboli vengono rifiutate. I metadati di rigore trattano le allow-list come sottoinsiemi, le deny-list come sovrainsiemi e i booleani richiesti come requisiti fissi. La policy di postura dei container viene valutata solo rispetto all’evidenza che OpenClaw può osservare per l’agente corrispondente. Se una regola sandbox.containers.* abilitata si applica a un agente il cui backend sandbox non può esporre quel campo, policy segnala policy/sandbox-container-posture-unobservable invece di trattare la dichiarazione come superata. Usa ambiti agentIds separati per gruppi di agenti che usano backend sandbox diversi e lascia le regole container non supportate non impostate o false per i gruppi in cui quei campi non possono essere osservati. ingress.session.requireDmScope di primo livello resta globale perché session.dmScope non è evidenza attribuibile a un canale.

Selettore	Sezioni supportate	Usalo quando
`agentIds`	`tools`, `agents.workspace`, `sandbox`, `dataHandling.memory` e `execApprovals`	Uno o più agenti runtime richiedono regole più restrittive.
`channelIds`	`ingress.channels`	Uno o più canali richiedono regole di ingress più restrittive.

Ogni ambito presente in policy.jsonc deve essere valido e applicabile.

Canali

Campo policy	Stato osservato	Usalo quando
`channels.denyRules[].when.provider`	Provider `channels.*` e stato di abilitazione	Nega i canali configurati da un provider come `telegram`.
`channels.denyRules[].reason`	Messaggio del finding e contesto del suggerimento di riparazione	Spiega perché il provider è negato.

Server MCP

Campo policy	Stato osservato	Usalo quando
`mcp.servers.allow`	ID `mcp.servers.*`	Richiedi che ogni server MCP configurato sia in un’allowlist.
`mcp.servers.deny`	ID `mcp.servers.*`	Nega ID specifici di server MCP configurati.

Provider di modelli

Campo policy	Stato osservato	Usalo quando
`models.providers.allow`	ID `models.providers.*` e riferimenti modello selezionati	Richiedi che i provider configurati e i riferimenti modello selezionati usino provider approvati.
`models.providers.deny`	ID `models.providers.*` e riferimenti modello selezionati	Nega i provider configurati e i riferimenti modello selezionati in base all’ID provider.

Rete

Campo policy	Stato osservato	Usalo quando
`network.privateNetwork.allow`	Vie di fuga SSRF della rete privata	Imposta su `false` per richiedere che l’accesso alla rete privata resti disabilitato.

Ingress e accesso ai canali

Campo policy	Stato osservato	Usalo quando
`ingress.session.requireDmScope`	`session.dmScope`	Richiedi un ambito di isolamento dei messaggi diretti revisionato.
`ingress.channels.allowDmPolicies`	`channels.*.dmPolicy` e campi legacy della policy DM del canale	Consenti solo policy di canale per messaggi diretti revisionate.
`ingress.channels.denyOpenGroups`	Policy di ingress per canale, account e gruppo	Nega l’ingress di gruppi aperti per canali e account configurati.
`ingress.channels.requireMentionInGroups`	Configurazione del gate di menzione per canale, account, gruppo, guild e annidamenti	Richiedi gate di menzione quando l’ingress di gruppo è aperto o vincolato a menzione.

Gateway

Campo policy	Stato osservato	Usalo quando
`gateway.exposure.allowNonLoopbackBind`	`gateway.bind`	Imposta su `false` per richiedere il binding loopback del Gateway.
`gateway.exposure.allowTailscaleFunnel`	Postura Tailscale serve/funnel del Gateway	Imposta su `false` per negare l’esposizione Tailscale Funnel.
`gateway.auth.requireAuth`	`gateway.auth.mode`	Imposta su `true` per rifiutare l’autenticazione Gateway disabilitata.
`gateway.auth.requireExplicitRateLimit`	`gateway.auth.rateLimit`	Imposta su `true` per richiedere una configurazione esplicita del rate limit di autenticazione.
`gateway.controlUi.allowInsecure`	Toggle non sicuri di autenticazione/dispositivo/origine della UI di controllo	Imposta su `false` per negare i toggle di esposizione non sicuri della UI di controllo.
`gateway.remote.allow`	Modalità/configurazione Gateway remoto	Imposta su `false` per negare la modalità Gateway remoto.
`gateway.http.denyEndpoints`	Endpoint API HTTP del Gateway	Nega ID di endpoint come `chatCompletions` o `responses`.
`gateway.http.requireUrlAllowlists`	Input di fetch URL HTTP del Gateway	Imposta su `true` per richiedere allowlist URL sugli input di fetch URL.

Workspace agente

Campo policy	Stato osservato	Usalo quando
`agents.workspace.allowedAccess`	`agents.defaults.sandbox.workspaceAccess` e `agents.list[].sandbox.workspaceAccess`	Consenti solo valori di accesso al workspace sandbox come `none` o `ro`.
`agents.workspace.denyTools`	Configurazione globale e per agente di negazione strumenti	Richiedi che strumenti di mutazione workspace/runtime come `exec`, `process`, `write`, `edit` o `apply_patch` siano negati.

Postura sandbox

Campo policy	Stato osservato	Usalo quando
`sandbox.requireMode`	`agents.defaults.sandbox.mode` e modalità per agente	Consenti solo modalità sandbox revisionate come `all` o `non-main`.
`sandbox.allowBackends`	`agents.defaults.sandbox.backend` e backend per agente	Consenti solo backend sandbox revisionati come `docker`.
`sandbox.containers.denyHostNetwork`	Modalità rete del sandbox/browser basato su container	Nega la modalità rete host.
`sandbox.containers.denyContainerNamespaceJoin`	Modalità rete del sandbox/browser basato su container	Nega l’adesione allo spazio dei nomi di rete di un altro container.
`sandbox.containers.requireReadOnlyMounts`	Modalità mount del sandbox/browser basato su container	Richiedi che i mount siano di sola lettura.
`sandbox.containers.denyContainerRuntimeSocketMounts`	Target di mount del sandbox/browser basato su container	Nega i mount dei socket runtime dei container.
`sandbox.containers.denyUnconfinedProfiles`	Postura del profilo di sicurezza del container	Nega profili di sicurezza container non confinati.
`sandbox.browser.requireCdpSourceRange`	Intervallo sorgente CDP del browser sandbox	Richiedi che l’esposizione CDP del browser dichiari un intervallo sorgente.

La policy tratta sandbox.mode mancante come default implicito off, quindi sandbox.requireMode segnala un sandbox nuovo o non configurato come fuori da un’allowlist come ["all"].

Gestione dei dati

Campo policy	Stato osservato	Usalo quando
`dataHandling.sensitiveLogging.requireRedaction`	`logging.redactSensitive`	Imposta su `true` per rifiutare `logging.redactSensitive: "off"`.
`dataHandling.telemetry.denyContentCapture`	`diagnostics.otel.captureContent`	Imposta su `true` per rifiutare l’acquisizione dei contenuti di telemetria.
`dataHandling.retention.requireSessionMaintenance`	`session.maintenance.mode`	Imposta su `true` per richiedere la modalità effettiva di manutenzione sessione `enforce`.
`dataHandling.memory.denySessionTranscriptIndexing`	`memory.qmd.sessions.enabled` e `agents.*.memorySearch.experimental.sessionMemory`	Imposta su `true` per rifiutare l’indicizzazione delle trascrizioni di sessione in memoria.

Segreti

Campo policy	Stato osservato	Usalo quando
`secrets.requireManagedProviders`	SecretRefs di configurazione e dichiarazioni `secrets.providers.*`	Imposta su `true` per richiedere che i SecretRefs puntino a provider dichiarati.
`secrets.denySources`	Origini dei provider di segreti e origini SecretRef	Nega origini come `exec`, `file` o un altro nome di origine configurato.
`secrets.allowInsecureProviders`	Flag di postura non sicura dei provider di segreti	Imposta su `false` per rifiutare provider che optano per una postura non sicura.

Approvazioni exec

La policy delle approvazioni exec osserva l’artefatto runtime attivo exec-approvals.json. Per default è ~/.openclaw/exec-approvals.json; quando OPENCLAW_STATE_DIR è impostato, Policy legge $OPENCLAW_STATE_DIR/exec-approvals.json. Le regole di postura effettive come execApprovals.defaults.* o execApprovals.agents.* richiedono evidenza leggibile dall’artefatto; un artefatto mancante o non valido viene segnalato come evidenza non osservabile invece di diventare un pass best-effort contro default runtime sintetici. Una volta che l’artefatto è leggibile, i campi di approvazione omessi ereditano i default runtime: defaults.security mancante è full, e la sicurezza agente mancante eredita quel default. L’evidenza include defaults, agents.* e agents.*.allowlist[].pattern più argPattern opzionale, postura effettiva autoAllowSkills e origine della voce. Non include percorso/token del socket, commandText, lastUsedCommand, percorsi risolti o timestamp.

Campo policy	Stato osservato	Da usare quando
`execApprovals.requireFile`	Percorso `exec-approvals.json` del runtime attivo	Impostare su `true` per richiedere che l’artefatto delle approvazioni esista e venga analizzato.
`execApprovals.defaults.allowSecurity`	`defaults.security`, con valore predefinito `full`	Consentire solo le modalita di sicurezza di approvazione predefinite approvate.
`execApprovals.agents.allowSecurity`	`agents.*.security`, che eredita i valori predefiniti	Consentire solo le modalita di sicurezza di approvazione effettive per agente approvate.
`execApprovals.agents.allowAutoAllowSkills`	`defaults.autoAllowSkills` e `agents.*.autoAllowSkills`, che ereditano i valori predefiniti del runtime	Impostare su `false` per richiedere allowlist manuali rigorose senza approvazione implicita della CLI delle skill.
`execApprovals.agents.allowlist.expected`	Pattern aggregato `agents.*.allowlist[]` e voci opzionali argPattern	Richiedere che la allowlist delle approvazioni corrisponda all’insieme di pattern revisionato.

Ad esempio, richiedere l’artefatto delle approvazioni, negare valori predefiniti permissivi e consentire solo la postura di approvazione exec revisionata per agenti selezionati:

{
  "execApprovals": {
    "requireFile": true,
    "defaults": {
      // Security modes: "deny", "allowlist", or "full".
      // This default permits only the locked-down deny posture.
      "allowSecurity": ["deny"],
    },
  },
  "scopes": {
    "restricted-shell": {
      "agentIds": ["family-agent", "groups-agent"],
      "execApprovals": {
        "agents": {
          // Selected agents may use reviewed allowlist posture, but not "full".
          "allowSecurity": ["allowlist"],
          // false means skill CLIs must appear in the reviewed allowlist instead of
          // being implicitly approved by autoAllowSkills.
          "allowAutoAllowSkills": false,
          "allowlist": {
            "expected": [
              // Simple entry: exact reviewed executable pattern with no argPattern.
              "travel-hub",
              // Constrained entry: pattern plus reviewed argument regex.
              { "pattern": "calendar-cli", "argPattern": "^sync\\b" },
              "/bin/date",
            ],
          },
        },
      },
    },
  },
}

Profili di autenticazione

Campo policy	Stato osservato	Da usare quando
`auth.profiles.requireMetadata`	Metadati provider e mode di `auth.profiles.*`	Richiedere chiavi di metadati come `provider` e `mode` nei profili di autenticazione della configurazione.
`auth.profiles.allowModes`	`auth.profiles.*.mode`	Consentire solo modalita dei profili di autenticazione supportate come `api_key`, `aws-sdk`, `oauth` o `token`.

Metadati degli strumenti

Campo policy	Stato osservato	Da usare quando
`tools.requireMetadata`	Dichiarazioni governate `TOOLS.md`	Richiedere agli strumenti governati di dichiarare chiavi di metadati come `risk`, `sensitivity` o `owner`.

Postura degli strumenti

Campo policy	Stato osservato	Da usare quando
`tools.profiles.allow`	`tools.profile` e `agents.list[].tools.profile`	Consentire solo id di profilo strumenti come `minimal`, `messaging` o `coding`.
`tools.fs.requireWorkspaceOnly`	`tools.fs.workspaceOnly` e override `tools.fs` per agente	Impostare su `true` per richiedere la postura dello strumento filesystem limitata al workspace.
`tools.exec.allowSecurity`	`tools.exec.security` e sicurezza exec per agente	Consentire solo modalita di sicurezza exec come `deny` o `allowlist`.
`tools.exec.requireAsk`	`tools.exec.ask` e modalita ask exec per agente	Richiedere una postura di approvazione come `always`.
`tools.exec.allowHosts`	`tools.exec.host` e routing host exec per agente	Consentire solo modalita di routing host exec come `sandbox`.
`tools.elevated.allow`	`tools.elevated.enabled` e postura elevata per agente	Impostare su `false` per richiedere che la modalita strumento elevata rimanga disabilitata.
`tools.alsoAllow.expected`	`tools.alsoAllow` e `tools.alsoAllow` per agente	Richiedere voci `alsoAllow` esatte e segnalare concessioni additive mancanti o inattese agli strumenti.
`tools.denyTools`	`tools.deny` e `agents.list[].tools.deny`	Richiedere che gli elenchi di negazione strumenti configurati includano id o gruppi di strumenti come `group:runtime` e `group:fs`.

Eseguire controlli solo policy durante la creazione:

openclaw policy check
openclaw policy check --json
openclaw policy check --severity-min error

policy check esegue solo l’insieme dei controlli policy ed emette evidenze, findings e hash di attestazione. Gli stessi findings compaiono anche in openclaw doctor --lint quando il Plugin Policy e abilitato. Confrontare un file policy operatore con un file policy baseline creato:

openclaw policy compare --baseline official.policy.jsonc
openclaw policy compare --baseline official.policy.jsonc --policy policy.jsonc --json

policy compare confronta la sintassi di un file policy con la sintassi di un file policy. Non ispeziona lo stato del runtime OpenClaw, evidenze, credenziali o segreti. Il comando usa gli stessi metadati delle regole policy che governano gli overlay con scope: le allowlist devono rimanere uguali o piu ristrette, le denylist devono rimanere uguali o piu ampie, i booleani richiesti devono mantenere il loro valore richiesto, le stringhe ordinate devono spostarsi solo verso l’estremita piu restrittiva dell’ordine configurato e gli elenchi esatti devono corrispondere. Il file baseline puo essere una policy creata dall’organizzazione. La policy controllata puo usare valori piu rigorosi o aggiungere regole policy extra. Una regola controllata di livello superiore puo anche soddisfare una regola baseline con scope quando e ugualmente o piu restrittiva, perche la policy di livello superiore si applica in modo ampio. I nomi degli scope non devono corrispondere; il confronto con scope e indicizzato per valore del selettore, come agentIds o channelIds, e per il campo policy controllato. Esempio di output JSON di confronto pulito che riporta solo lo stato del confronto dei file policy:

{
  "ok": true,
  "baselinePath": "official.policy.jsonc",
  "policyPath": "policy.jsonc",
  "rulesChecked": 3,
  "findings": []
}

Esempio di output pulito di policy check --json che include hash stabili che possono essere registrati da un operatore o supervisore:

{
  "ok": true,
  "attestation": {
    "policy": {
      "path": "policy.jsonc",
      "hash": "sha256:..."
    },
    "workspace": {
      "scope": "policy",
      "hash": "sha256:..."
    },
    "findingsHash": "sha256:...",
    "attestationHash": "sha256:..."
  },
  "checksRun": 5,
  "checksSkipped": 0,
  "findings": []
}

Configurare la policy

La configurazione della policy si trova sotto plugins.entries.policy.config.

{
  "plugins": {
    "entries": {
      "policy": {
        "enabled": true,
        "config": {
          "enabled": true,
          "path": "policy.jsonc",
          "workspaceRepairs": false,
          "expectedHash": "sha256:...",
          "expectedAttestationHash": "sha256:...",
        },
      },
    },
  },
}

Impostazione	Scopo
`enabled`	Abilitare i controlli policy anche prima che `policy.jsonc` esista.
`workspaceRepairs`	Consentire a `doctor --fix` di modificare impostazioni workspace gestite dalla policy.
`expectedHash`	Blocco hash opzionale per l’artefatto policy approvato.
`expectedAttestationHash`	Blocco hash opzionale per l’ultimo controllo policy pulito accettato.
`path`	Posizione relativa al workspace dell’artefatto policy.

Impostare plugins.entries.policy.config.enabled su false per disabilitare i controlli policy per un workspace lasciando installato il plugin. I requisiti dei metadati degli strumenti vengono creati in policy.jsonc con tools.requireMetadata, ad esempio ["risk", "sensitivity", "owner"].

Accettare lo stato policy

Esempio di output JSON:

{
  "ok": true,
  "attestation": {
    "checkedAt": "2026-05-10T20:00:00.000Z",
    "policy": {
      "path": "policy.jsonc",
      "hash": "sha256:..."
    },
    "workspace": {
      "scope": "policy",
      "hash": "sha256:..."
    },
    "findingsHash": "sha256:...",
    "attestationHash": "sha256:..."
  },
  "evidence": {
    "channels": [
      {
        "id": "telegram",
        "provider": "telegram",
        "source": "oc://openclaw.config/channels/telegram",
        "enabled": false
      }
    ],
    "mcpServers": [
      {
        "id": "docs",
        "transport": "stdio",
        "source": "oc://openclaw.config/mcp/servers/docs",
        "command": "npx"
      }
    ],
    "modelProviders": [
      {
        "id": "openai",
        "source": "oc://openclaw.config/models/providers/openai"
      }
    ],
    "modelRefs": [
      {
        "ref": "openai/gpt-5.5",
        "provider": "openai",
        "model": "gpt-5.5",
        "source": "oc://openclaw.config/agents/defaults/model"
      }
    ],
    "network": [
      {
        "id": "browser-private-network",
        "source": "oc://openclaw.config/browser/ssrfPolicy/dangerouslyAllowPrivateNetwork",
        "value": false
      }
    ],
    "gatewayExposure": [
      {
        "id": "gateway-bind",
        "kind": "bind",
        "source": "oc://openclaw.config/gateway/bind",
        "value": "loopback",
        "nonLoopback": false,
        "explicit": true
      }
    ],
    "agentWorkspace": [
      {
        "id": "agents-defaults-workspace-access",
        "kind": "workspaceAccess",
        "source": "oc://openclaw.config/agents/defaults/sandbox/workspaceAccess",
        "scope": "defaults",
        "value": "ro",
        "sandboxMode": "all",
        "sandboxModeSource": "oc://openclaw.config/agents/defaults/sandbox/mode",
        "sandboxEnabled": true,
        "explicit": true
      },
      {
        "id": "agents-defaults-tool-exec",
        "kind": "toolDeny",
        "source": "oc://openclaw.config/tools/deny",
        "scope": "defaults",
        "tool": "exec",
        "denied": true,
        "explicit": true
      }
    ],
    "secrets": [
      {
        "id": "vault",
        "kind": "provider",
        "source": "oc://openclaw.config/secrets/providers/vault",
        "providerSource": "env"
      },
      {
        "id": "oc://openclaw.config/models/providers/openai/apiKey",
        "kind": "input",
        "source": "oc://openclaw.config/models/providers/openai/apiKey",
        "provenance": "secretRef",
        "refSource": "env",
        "refProvider": "vault"
      }
    ],
    "authProfiles": [
      {
        "id": "github",
        "source": "oc://openclaw.config/auth/profiles/github",
        "validMetadata": true,
        "provider": "github",
        "mode": "token"
      }
    ],
    "tools": [
      {
        "id": "deploy",
        "source": "oc://TOOLS.md/tools/deploy",
        "line": 12,
        "risk": "critical",
        "sensitivity": "restricted",
        "capabilities": ["IRREVERSIBLE_EXTERNAL"]
      }
    ]
  },
  "checksRun": 30,
  "checksSkipped": 0,
  "findings": []
}

L’hash della policy identifica l’artefatto della regola redatto. Il blocco evidence registra lo stato OpenClaw osservato usato dai controlli della policy. Il valore workspace.hash identifica quel payload di evidenza per l’ambito controllato. L’hash dei finding identifica l’esatto insieme di finding restituito dal controllo. checkedAt registra quando è stata eseguita la valutazione. L’hash di attestazione identifica la dichiarazione stabile: hash della policy, hash dell’evidenza, hash dei finding e se il risultato era pulito. Intenzionalmente non include checkedAt, quindi lo stesso stato della policy produce la stessa attestazione in controlli ripetuti. Insieme, questi formano la tupla di audit per questo controllo della policy. Se un Gateway o un supervisore successivo usa la policy per bloccare, approvare o annotare un’azione runtime, deve registrare l’hash di attestazione dell’ultimo controllo della policy pulito. checkedAt rimane nell’output JSON per i log di audit, ma non fa parte dell’hash di attestazione stabile. Usa questo ciclo di vita quando accetti lo stato della policy:

Redigi o rivedi policy.jsonc.
Esegui openclaw policy check --json.
Se il risultato è pulito, registra attestation.policy.hash come expectedHash.
Registra attestation.attestationHash come expectedAttestationHash.
Riesegui openclaw doctor --lint in CI o nei gate di rilascio.

Se le regole della policy cambiano intenzionalmente, aggiorna entrambi gli hash accettati da un controllo pulito. Se le impostazioni del workspace cambiano intenzionalmente ma la policy rimane la stessa, di solito cambia solo expectedAttestationHash. L’abilitazione o l’aggiornamento delle regole agents.workspace aggiunge evidenze agentWorkspace all’hash del workspace e all’hash di attestazione. Gli operatori devono rivedere le nuove evidenze e aggiornare gli hash di attestazione accettati dopo aver abilitato queste regole. L’abilitazione o l’aggiornamento delle regole di postura degli strumenti aggiunge evidenze toolPosture nello stesso modo. openclaw policy watch esegue ripetutamente lo stesso controllo e segnala quando l’evidenza corrente non corrisponde più a expectedAttestationHash:

openclaw policy watch --json

Usa --once in CI o negli script che richiedono una sola valutazione della deriva. Senza --once, il comando esegue il polling ogni due secondi per impostazione predefinita; usa --interval-ms per scegliere un intervallo diverso.

Finding

La policy attualmente verifica:

ID controllo	Riscontro
`policy/policy-jsonc-missing`	La policy è abilitata ma `policy.jsonc` manca.
`policy/policy-jsonc-invalid`	La policy non può essere analizzata o contiene voci di regola malformate.
`policy/policy-hash-mismatch`	La policy non corrisponde a `expectedHash` configurato.
`policy/attestation-hash-mismatch`	Le prove della policy corrente non corrispondono più all’attestazione accettata.
`policy/policy-conformance-invalid`	Un file di policy di baseline o verificato ha una sintassi di confronto non valida.
`policy/policy-conformance-missing`	A un file di policy verificato manca una regola richiesta dal file di policy di baseline.
`policy/policy-conformance-weaker`	Un file di policy verificato ha un valore più debole rispetto al file di policy di baseline.
`policy/channels-denied-provider`	Un canale abilitato corrisponde a una regola di negazione dei canali.
`policy/mcp-denied-server`	Un server MCP configurato è negato dalla policy.
`policy/mcp-unapproved-server`	Un server MCP configurato è fuori dall’allowlist.
`policy/models-denied-provider`	Un provider di modelli configurato o un riferimento di modello usa un provider negato.
`policy/models-unapproved-provider`	Un provider di modelli configurato o un riferimento di modello è fuori dall’allowlist.
`policy/network-private-access-enabled`	Una via di uscita SSRF verso rete privata è abilitata quando la policy la nega.
`policy/ingress-dm-policy-unapproved`	Una policy DM del canale è fuori dall’allowlist della policy.
`policy/ingress-dm-scope-unapproved`	`session.dmScope` non corrisponde all’ambito di isolamento DM richiesto dalla policy.
`policy/ingress-open-groups-denied`	Una policy di gruppo del canale è `open` mentre la policy nega l’ingresso a gruppi aperti.
`policy/ingress-group-mention-required`	Una voce di canale o gruppo disabilita i gate di menzione mentre la policy li richiede.
`policy/gateway-non-loopback-bind`	La postura di bind del Gateway consente esposizione non local loopback quando la policy la nega.
`policy/gateway-auth-disabled`	L’autenticazione del Gateway è disabilitata quando la policy richiede l’autenticazione.
`policy/gateway-rate-limit-missing`	La postura del limite di frequenza dell’autenticazione del Gateway non è esplicita quando la policy la richiede.
`policy/gateway-control-ui-insecure`	Le opzioni di esposizione non sicura della Control UI del Gateway sono abilitate.
`policy/gateway-tailscale-funnel`	L’esposizione Tailscale Funnel del Gateway è abilitata quando la policy la nega.
`policy/gateway-remote-enabled`	La modalità remota del Gateway è attiva quando la policy la nega.
`policy/gateway-http-endpoint-enabled`	Un endpoint API HTTP del Gateway è abilitato mentre è negato dalla policy.
`policy/gateway-http-url-fetch-unrestricted`	L’input di recupero URL HTTP del Gateway non ha l’allowlist URL richiesta.
`policy/agents-workspace-access-denied`	La modalità sandbox dell’agente o l’accesso al workspace è fuori dall’allowlist della policy.
`policy/agents-tool-not-denied`	Una configurazione agente o predefinita non nega uno strumento richiesto dalla policy.
`policy/tools-profile-unapproved`	Un profilo strumenti globale o per agente configurato è fuori dall’allowlist.
`policy/tools-fs-workspace-only-required`	Gli strumenti del filesystem non sono configurati con postura dei percorsi solo workspace.
`policy/tools-exec-security-unapproved`	La modalità di sicurezza exec è fuori dall’allowlist della policy.
`policy/tools-exec-ask-unapproved`	La modalità ask di exec è fuori dall’allowlist della policy.
`policy/tools-exec-host-unapproved`	Il routing host di exec è fuori dall’allowlist della policy.
`policy/tools-elevated-enabled`	La modalità strumento elevata è abilitata quando la policy la nega.
`policy/tools-also-allow-missing`	A una lista `alsoAllow` configurata manca una voce richiesta dalla policy.
`policy/tools-also-allow-unexpected`	Una lista `alsoAllow` configurata include una voce non attesa dalla policy.
`policy/tools-required-deny-missing`	Una lista di negazione strumenti globale o per agente non include uno strumento negato richiesto.
`policy/sandbox-mode-unapproved`	La modalità sandbox è fuori dall’allowlist della policy.
`policy/sandbox-backend-unapproved`	Il backend sandbox è fuori dall’allowlist della policy.
`policy/sandbox-container-posture-unobservable`	Una regola di postura del container è abilitata per un backend che non può osservarla.
`policy/sandbox-container-host-network-denied`	Una sandbox o un browser basato su container usa la modalità rete host.
`policy/sandbox-container-namespace-join-denied`	Una sandbox o un browser basato su container si unisce al namespace di un altro container.
`policy/sandbox-container-mount-mode-required`	Un mount di una sandbox o di un browser basato su container non è di sola lettura.
`policy/sandbox-container-runtime-socket-mount`	Un mount di una sandbox o di un browser basato su container espone il socket del runtime del container.
`policy/sandbox-container-unconfined-profile`	Il profilo sandbox del container è senza confinamento quando la policy lo nega.
`policy/sandbox-browser-cdp-source-range-missing`	L’intervallo sorgente CDP del browser sandbox manca quando la policy ne richiede uno.
`policy/data-handling-redaction-disabled`	La redazione dei log sensibili è disabilitata quando la policy la richiede.
`policy/data-handling-telemetry-content-capture`	L’acquisizione del contenuto della telemetria è abilitata quando la policy la nega.
`policy/data-handling-session-retention-not-enforced`	La manutenzione della conservazione delle sessioni non è applicata quando la policy la richiede.
`policy/data-handling-session-transcript-memory-enabled`	L’indicizzazione in memoria delle trascrizioni di sessione è abilitata quando la policy la nega.
`policy/secrets-unmanaged-provider`	Un SecretRef di configurazione fa riferimento a un provider non dichiarato in `secrets.providers`.
`policy/secrets-denied-provider-source`	Un provider di segreti di configurazione o SecretRef usa una sorgente negata dalla policy.
`policy/secrets-insecure-provider`	Un provider di segreti opta per una postura non sicura quando la policy la nega.
`policy/auth-profile-invalid-metadata`	A un profilo di autenticazione di configurazione mancano metadati validi di provider o modalità.
`policy/auth-profile-unapproved-mode`	Una modalità di profilo di autenticazione di configurazione è fuori dall’allowlist della policy.
`policy/exec-approvals-missing`	La policy richiede `exec-approvals.json`, ma l’artefatto manca.
`policy/exec-approvals-invalid`	L’artefatto delle approvazioni exec configurato non può essere analizzato.
`policy/exec-approvals-default-security-unapproved`	I valori predefiniti di approvazione exec usano una modalità di sicurezza fuori dall’allowlist della policy.
`policy/exec-approvals-agent-security-unapproved`	Una modalità di sicurezza effettiva di approvazione exec per agente è fuori dall’allowlist.
`policy/exec-approvals-auto-allow-skills-enabled`	Un agente di approvazione exec consente automaticamente in modo implicito le CLI skill quando la policy lo nega.
`policy/exec-approvals-allowlist-missing`	All’allowlist delle approvazioni manca un pattern richiesto dalla policy.
`policy/exec-approvals-allowlist-unexpected`	L’allowlist delle approvazioni include un pattern non atteso dalla policy.
`policy/tools-missing-risk-level`	A una dichiarazione di strumento governato mancano i metadati di rischio.
`policy/tools-unknown-risk-level`	Una dichiarazione di strumento governato usa un valore di rischio sconosciuto.
`policy/tools-missing-sensitivity-token`	A una dichiarazione di strumento governato mancano i metadati di sensibilità.
`policy/tools-missing-owner`	A una dichiarazione di strumento governato mancano i metadati del proprietario.
`policy/tools-unknown-sensitivity-token`	Una dichiarazione di strumento governato usa un valore di sensibilità sconosciuto.

I riscontri della policy possono includere sia target sia requirement. target è l’elemento osservato nel workspace che non è conforme. requirement è la regola di policy scritta che lo ha reso un riscontro. Entrambi i valori oggi sono indirizzi, di solito percorsi oc://, ma i nomi dei campi descrivono il loro ruolo nella policy anziché il formato dell’indirizzo. Esempio di riscontro JSON:

{
  "checkId": "policy/channels-denied-provider",
  "severity": "error",
  "message": "Channel 'telegram' uses denied provider 'telegram'.",
  "source": "policy",
  "path": "openclaw config",
  "ocPath": "oc://openclaw.config/channels/telegram",
  "target": "oc://openclaw.config/channels/telegram",
  "requirement": "oc://policy.jsonc/channels/denyRules/#0",
  "fixHint": "Telegram is not approved for this workspace."
}

Esempio di riscontro strumento:

{
  "checkId": "policy/tools-missing-risk-level",
  "severity": "error",
  "message": "TOOLS.md tool 'deploy' has no explicit risk classification.",
  "source": "policy",
  "path": "TOOLS.md",
  "line": 12,
  "ocPath": "oc://TOOLS.md/tools/deploy",
  "target": "oc://TOOLS.md/tools/deploy",
  "requirement": "oc://policy.jsonc/tools/requireMetadata"
}

Esempio di riscontro MCP:

{
  "checkId": "policy/mcp-unapproved-server",
  "severity": "error",
  "message": "MCP server 'remote' is not in the policy allowlist.",
  "source": "policy",
  "path": "openclaw config",
  "ocPath": "oc://openclaw.config/mcp/servers/remote",
  "target": "oc://openclaw.config/mcp/servers/remote",
  "requirement": "oc://policy.jsonc/mcp/servers/allow"
}

Esempio di riscontro provider di modelli:

{
  "checkId": "policy/models-unapproved-provider",
  "severity": "error",
  "message": "Model ref 'anthropic/claude-sonnet-4.7' uses unapproved provider 'anthropic'.",
  "source": "policy",
  "path": "openclaw config",
  "ocPath": "oc://openclaw.config/agents/defaults/model/fallbacks/#0",
  "target": "oc://openclaw.config/agents/defaults/model/fallbacks/#0",
  "requirement": "oc://policy.jsonc/models/providers/allow"
}

Esempio di riscontro rete:

{
  "checkId": "policy/network-private-access-enabled",
  "severity": "error",
  "message": "Network setting 'browser-private-network' allows private-network access.",
  "source": "policy",
  "path": "openclaw config",
  "ocPath": "oc://openclaw.config/browser/ssrfPolicy/dangerouslyAllowPrivateNetwork",
  "target": "oc://openclaw.config/browser/ssrfPolicy/dangerouslyAllowPrivateNetwork",
  "requirement": "oc://policy.jsonc/network/privateNetwork/allow"
}

Esempio di rilevamento dell’esposizione del Gateway:

{
  "checkId": "policy/gateway-non-loopback-bind",
  "severity": "error",
  "message": "Gateway bind setting 'gateway-bind' permits non-loopback exposure.",
  "source": "policy",
  "path": "openclaw config",
  "ocPath": "oc://openclaw.config/gateway/bind",
  "target": "oc://openclaw.config/gateway/bind",
  "requirement": "oc://policy.jsonc/gateway/exposure/allowNonLoopbackBind"
}

Esempio di rilevamento dell’area di lavoro dell’agente:

{
  "checkId": "policy/agents-workspace-access-denied",
  "severity": "error",
  "message": "agents.defaults sandbox workspaceAccess 'rw' is not allowed by policy.",
  "source": "policy",
  "path": "openclaw config",
  "ocPath": "oc://openclaw.config/agents/defaults/sandbox/workspaceAccess",
  "target": "oc://openclaw.config/agents/defaults/sandbox/workspaceAccess",
  "requirement": "oc://policy.jsonc/agents/workspace/allowedAccess"
}

Riparazione

doctor --lint e policy check sono in sola lettura. doctor --fix modifica solo le impostazioni dell’area di lavoro gestite dalla policy quando workspaceRepairs è abilitato esplicitamente. Senza questa adesione esplicita, i controlli delle policy segnalano ciò che riparerebbero e lasciano le impostazioni invariate. In questa versione, la riparazione può disabilitare i canali che sono abilitati nella configurazione OpenClaw ma negati da channels.denyRules. Abilita workspaceRepairs solo dopo che il file delle policy è stato revisionato, perché una regola di negazione valida può disattivare un canale configurato:

{
  "plugins": {
    "entries": {
      "policy": {
        "config": {
          "workspaceRepairs": true,
        },
      },
    },
  },
}

Codici di uscita

Comando	`0`	`1`	`2`
`policy check`	Nessun rilevamento alla soglia.	Uno o più rilevamenti hanno raggiunto la soglia.	Errore di argomento o runtime.
`policy compare`	Il file delle policy è almeno rigoroso quanto il riferimento.	Il file delle policy non è valido, manca o è più debole delle regole di riferimento.	Errore di argomento o runtime.
`policy watch`	Nessun rilevamento e l’hash accettato è aggiornato.	Esistono rilevamenti o l’attestazione accettata è obsoleta.	Errore di argomento o runtime.

Criterio

`openclaw policy`

Avvio rapido

Riferimento alle regole di policy

Overlay con ambito

Canali

Server MCP

Provider di modelli

Rete

Ingress e accesso ai canali

Gateway

Workspace agente

Postura sandbox

Gestione dei dati

Segreti

Approvazioni exec

Profili di autenticazione

Metadati degli strumenti

Postura degli strumenti

Configurare la policy

Accettare lo stato policy

Finding

Riparazione

Codici di uscita

Correlati

​openclaw policy

​Avvio rapido

​Riferimento alle regole di policy

​Overlay con ambito

​Canali

​Server MCP

​Provider di modelli

​Rete

​Ingress e accesso ai canali

​Gateway

​Workspace agente

​Postura sandbox

​Gestione dei dati

​Segreti

​Approvazioni exec

​Profili di autenticazione

​Metadati degli strumenti

​Postura degli strumenti

​Configurare la policy

​Accettare lo stato policy

​Finding

​Riparazione

​Codici di uscita

​Correlati

`openclaw policy`

Avvio rapido

Riferimento alle regole di policy

Overlay con ambito

Canali

Server MCP

Provider di modelli

Rete

Ingress e accesso ai canali

Gateway

Workspace agente

Postura sandbox

Gestione dei dati

Segreti

Approvazioni exec

Profili di autenticazione

Metadati degli strumenti

Postura degli strumenti

Configurare la policy

Accettare lo stato policy

Finding

Riparazione

Codici di uscita

Correlati