`openclaw policy`

openclaw policy é fornecido pelo Plugin de Política incluído. Ele é uma camada de conformidade empresarial sobre as configurações existentes do OpenClaw, não um segundo sistema de configuração. Você define os requisitos em policy.jsonc; o OpenClaw observa o workspace ativo como evidência; a política relata desvios por meio de doctor --lint. A política não impõe chamadas de ferramentas nem reescreve o comportamento do runtime no momento da solicitação e não atesta armazenamentos de credenciais por agente, como auth-profiles.json. A política verifica canais configurados, servidores MCP, provedores de modelos, postura de SSRF da rede, acesso de entrada/canais, exposição do Gateway e postura de comandos de Node, acesso dos agentes ao workspace, postura de sandbox, postura de tratamento de dados, postura de provedores de segredos/perfis de autenticação e metadados de ferramentas sob governança (TOOLS.md). Use-a quando um workspace precisar de uma declaração durável e verificável, como “o Telegram não deve estar habilitado” ou “ferramentas sob governança devem declarar metadados de risco e responsável”. Se você precisar apenas de comportamento local, sem atestação ou detecção de desvios, a configuração comum é suficiente.

Início rápido

openclaw plugins enable policy

O Plugin permanece habilitado mesmo quando policy.jsonc está ausente, para que o doctor possa relatar a ausência do artefato em vez de ignorar silenciosamente as verificações. Crie policy.jsonc manualmente; ele não é gerado com base nas configurações atuais. Cada seção de nível superior é um namespace de regras: uma verificação só é executada quando há uma regra concreta nela (seções ou chaves não compatíveis falham como policy/policy-jsonc-invalid, em vez de serem ignoradas silenciosamente). Exemplo mínimo que abrange todas as seções compatíveis:

{
  "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,
    },
    "nodes": {
      "denyCommands": ["system.run"],
    },
  },
  "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"],
  },
}

Observações abrangentes que não são evidentes nas tabelas de regras abaixo:

Omitir gateway.bind enquanto associações que não sejam local loopback são negadas significa que você aceita o padrão do runtime; defina gateway.bind: "loopback" para obter conformidade estrita.
Para um agente somente leitura, defina o mode do sandbox como all ou non-main nos padrões ou no agente aplicável e defina workspaceAccess como none ou ro. Um modo de sandbox ausente ou definido como off não atende a uma política somente leitura.
agents.workspace.denyTools aceita exec, process, write, edit, apply_patch. Os grupos de negação de ferramentas da configuração group:fs (alteração de arquivos) e group:runtime (shell/processo) atendem à postura equivalente.
As verificações de aprovações de execução leem o artefato ativo exec-approvals.json somente quando há uma regra execApprovals; um artefato ausente ou inválido constitui evidência não observável, não uma aprovação sintética.
As evidências de segredos e perfis de autenticação registram apenas a postura do provedor/origem e os metadados de SecretRef, nunca valores brutos. A política não lê nem atesta armazenamentos de credenciais por agente, como auth-profiles.json.
A evidência de tratamento de dados representa apenas a postura no nível da configuração (modo de redação, controle de captura de telemetria, modo de manutenção de sessões e configuração de indexação de transcrições). Ela não inspeciona logs, exportações de telemetria, transcrições ou arquivos de memória, e um resultado sem problemas não comprova que eles não contenham dados pessoais ou segredos.

Referência das regras de política

Todas as regras abaixo são opcionais; uma verificação só é executada quando a regra está presente. O estado observado corresponde à configuração existente do OpenClaw ou aos metadados do workspace.

Sobreposições com escopo

Use scopes.<scopeName> quando agentes ou canais específicos precisarem de uma política mais estrita que a linha de base de nível superior. O nome do escopo é apenas um rótulo; a correspondência usa o seletor dentro do escopo. As sobreposições são aditivas: a regra global continua sendo executada, e a regra com escopo pode adicionar sua própria constatação sobre a mesma evidência.

Seletor	Seções compatíveis	Use quando
`agentIds`	`tools`, `agents.workspace`, `sandbox`, `dataHandling.memory`, `execApprovals`	Um ou mais agentes de runtime precisam de regras mais estritas.
`channelIds`	`ingress.channels`	Um ou mais canais precisam de regras de entrada mais estritas.

Se uma entrada de agentIds não estiver presente em agents.list[], o OpenClaw avalia a regra com escopo em relação à postura global/padrão herdada para esse ID de agente de runtime, em vez de ignorá-la.

{
  "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,
        },
      },
    },
  },
}

O mesmo agente pode aparecer em vários escopos se cada escopo controlar um campo diferente, como no exemplo acima. Um campo com escopo repetido para o mesmo agente deve ser igualmente ou mais restritivo; uma declaração duplicada mais permissiva é rejeitada (listas de permissões devem ser subconjuntos, listas de negações devem ser superconjuntos e booleanos obrigatórios são fixos). As regras de postura de contêiner (sandbox.containers.*) são verificadas apenas em relação às evidências que o backend de sandbox do agente correspondente consegue expor. Se um backend não puder observar uma regra habilitada para ele, a política relatará policy/sandbox-container-posture-unobservable em vez de aprová-la; aplique as regras de contêiner aos grupos de agentes que usam um backend capaz de expô-las. ingress.session.requireDmScope no nível superior permanece global; session.dmScope não é uma evidência atribuível a um canal e, portanto, não pode receber escopo por channelIds. Todos os escopos presentes em policy.jsonc devem ser válidos e aplicáveis.

Canais

Campo da política	Estado observado	Use quando
`channels.denyRules[].when.provider`	Provedor e estado habilitado de `channels.*`	Para negar canais configurados de um provedor como `telegram`.
`channels.denyRules[].reason`	Mensagem da constatação e contexto da orientação de correção	Para explicar por que o provedor é negado.

Servidores MCP

Campo da política	Estado observado	Use quando
`mcp.servers.allow`	IDs de `mcp.servers.*`	Para exigir que todos os servidores MCP configurados estejam em uma lista de permissões.
`mcp.servers.deny`	IDs de `mcp.servers.*`	Para negar IDs específicos de servidores MCP configurados.

Provedores de modelos

Campo da política	Estado observado	Use quando
`models.providers.allow`	IDs de `models.providers.*` e referências de modelos selecionadas	Para exigir que provedores configurados e referências de modelos selecionadas usem provedores aprovados.
`models.providers.deny`	IDs de `models.providers.*` e referências de modelos selecionadas	Para negar provedores configurados e referências de modelos selecionadas pelo ID do provedor.

Rede

Campo da política	Estado observado	Use quando
`network.privateNetwork.allow`	Mecanismos de escape de SSRF da rede privada	Defina como `false` para exigir que o acesso à rede privada permaneça desabilitado.

Entrada e acesso a canais

Campo da política	Estado observado	Use quando
`ingress.session.requireDmScope`	`session.dmScope`	Exigir um escopo revisado de isolamento de mensagens diretas.
`ingress.channels.allowDmPolicies`	`channels.*.dmPolicy` e campos legados de política de DM do canal	Permitir apenas políticas revisadas de canais de mensagens diretas.
`ingress.channels.denyOpenGroups`	Política de entrada de canal, conta e grupo	Negar entrada de grupos abertos para canais e contas configurados.
`ingress.channels.requireMentionInGroups`	Configuração de restrição por menção de canal, conta, grupo, servidor e níveis aninhados	Exigir restrições por menção quando a entrada de grupos estiver aberta ou condicionada a menções.

Gateway

Campo da política	Estado observado	Use quando
`gateway.exposure.allowNonLoopbackBind`	`gateway.bind`	Definir como `false` para exigir que o Gateway seja vinculado ao loopback.
`gateway.exposure.allowTailscaleFunnel`	Postura de serviço/funil do Gateway no Tailscale	Definir como `false` para negar a exposição pelo Tailscale Funnel.
`gateway.auth.requireAuth`	`gateway.auth.mode`	Definir como `true` para rejeitar a autenticação desativada do Gateway.
`gateway.auth.requireExplicitRateLimit`	`gateway.auth.rateLimit`	Definir como `true` para exigir uma configuração explícita de limite de taxa de autenticação.
`gateway.controlUi.allowInsecure`	Opções inseguras de autenticação/dispositivo/origem da interface de controle	Definir como `false` para negar opções de exposição insegura da interface de controle.
`gateway.remote.allow`	Modo/configuração de Gateway remoto	Definir como `false` para negar o modo de Gateway remoto.
`gateway.http.denyEndpoints`	Endpoints da API HTTP do Gateway	Negar IDs de endpoints, como `chatCompletions` ou `responses`.
`gateway.http.requireUrlAllowlists`	Entradas de busca de URL do Gateway via HTTP	Definir como `true` para exigir listas de permissões de URLs nas entradas de busca de URL.
`gateway.nodes.denyCommands`	`gateway.nodes.denyCommands`	Exigir que IDs exatos de comandos de Node, como `system.run`, sejam negados na configuração do OpenClaw.

gateway.nodes.denyCommands é uma regra exata, com distinção entre maiúsculas e minúsculas, que exige um superconjunto de negações. Use-a quando a política precisar comprovar que comandos privilegiados de Node estão explicitamente negados pela configuração do OpenClaw. Uma implantação que permita intencionalmente um comando privilegiado de Node deve atualizar policy.jsonc após a revisão, em vez de depender apenas de gateway.nodes.allowCommands.

Espaço de trabalho do agente

Campo da política	Estado observado	Use quando
`agents.workspace.allowedAccess`	`agents.defaults.sandbox.workspaceAccess` e `agents.list[].sandbox.workspaceAccess`	Permitir apenas valores de acesso ao espaço de trabalho do sandbox, como `none` ou `ro`.
`agents.workspace.denyTools`	Configuração global e por agente de negação de ferramentas	Exigir que as ferramentas de mutação (`exec`, `process`, `write`, `edit`, `apply_patch`) sejam negadas.

Postura do sandbox

Campo da política	Estado observado	Use quando
`sandbox.requireMode`	`agents.defaults.sandbox.mode` e modo por agente	Permitir apenas modos de sandbox revisados, como `all` ou `non-main`.
`sandbox.allowBackends`	`agents.defaults.sandbox.backend` e backend por agente	Permitir apenas backends de sandbox revisados, como `docker`.
`sandbox.containers.denyHostNetwork`	Modo de rede de sandbox/navegador baseado em contêiner	Negar o modo de rede do host.
`sandbox.containers.denyContainerNamespaceJoin`	Modo de rede de sandbox/navegador baseado em contêiner	Negar a associação ao namespace de rede de outro contêiner.
`sandbox.containers.requireReadOnlyMounts`	Modo de montagem de sandbox/navegador baseado em contêiner	Exigir que as montagens sejam somente leitura.
`sandbox.containers.denyContainerRuntimeSocketMounts`	Destinos de montagem de sandbox/navegador baseado em contêiner	Negar montagens de sockets do runtime de contêineres.
`sandbox.containers.denyUnconfinedProfiles`	Postura dos perfis de segurança de contêiner	Negar perfis de segurança de contêiner sem confinamento.
`sandbox.browser.requireCdpSourceRange`	Intervalo de origem do CDP do navegador do sandbox	Exigir que a exposição do CDP do navegador declare um intervalo de origem.

A política considera a ausência de sandbox.mode como seu padrão implícito off; portanto, sandbox.requireMode informa que um sandbox novo ou não configurado está fora de uma lista de permissões como ["all"].

Tratamento de dados

Campo da política	Estado observado	Use quando
`dataHandling.sensitiveLogging.requireRedaction`	`logging.redactSensitive`	Definir como `true` para rejeitar `logging.redactSensitive: "off"`.
`dataHandling.telemetry.denyContentCapture`	`diagnostics.otel.captureContent`	Definir como `true` para rejeitar a captura de conteúdo por telemetria.
`dataHandling.retention.requireSessionMaintenance`	`session.maintenance.mode`	Definir como `true` para exigir o modo efetivo de manutenção de sessão `enforce`.
`dataHandling.memory.denySessionTranscriptIndexing`	`memory.qmd.sessions.enabled` e `agents.*.memorySearch.experimental.sessionMemory`	Definir como `true` para rejeitar a indexação de transcrições de sessões na memória.

Segredos

Campo da política	Estado observado	Use quando
`secrets.requireManagedProviders`	SecretRefs da configuração e declarações `secrets.providers.*`	Definir como `true` para exigir que SecretRefs apontem para provedores declarados.
`secrets.denySources`	Fontes de provedores de segredos e fontes de SecretRef	Negar fontes como `exec`, `file` ou outro nome de fonte configurado.
`secrets.allowInsecureProviders`	Indicadores de postura insegura de provedores de segredos	Definir como `false` para rejeitar provedores que optem por uma postura insegura.

Aprovações de execução

As verificações de aprovação de execução leem o artefato de runtime exec-approvals.json: ~/.openclaw/exec-approvals.json por padrão ou $OPENCLAW_STATE_DIR/exec-approvals.json quando OPENCLAW_STATE_DIR estiver definido. As regras de postura em execApprovals.defaults.* ou execApprovals.agents.* exigem evidências legíveis do artefato; um artefato ausente ou inválido é informado como evidência não observável, em vez de uma aprovação baseada em melhor esforço. Quando o artefato é legível, os campos omitidos herdam os padrões do runtime: a ausência de defaults.security equivale a full, e a ausência da segurança do agente herda esse padrão. As evidências incluem defaults, agents.*, agents.*.allowlist[].pattern, o argPattern opcional, a postura efetiva de autoAllowSkills e a origem da entrada — nunca o caminho/token do socket, commandText, lastUsedCommand, caminhos resolvidos ou carimbos de data e hora.

Campo da política	Estado observado	Use quando
`execApprovals.requireFile`	Caminho ativo de runtime de `exec-approvals.json`	Definir como `true` para exigir que o artefato de aprovações exista e possa ser analisado.
`execApprovals.defaults.allowSecurity`	`defaults.security`, com padrão `full`	Permitir apenas modos aprovados de segurança padrão das aprovações.
`execApprovals.agents.allowSecurity`	`agents.*.security`, herdando os padrões	Permitir apenas modos efetivos aprovados de segurança das aprovações por agente.
`execApprovals.agents.allowAutoAllowSkills`	`defaults.autoAllowSkills` e `agents.*.autoAllowSkills`, herdando os padrões do runtime	Definir como `false` para exigir listas de permissões manuais estritas sem aprovação implícita da CLI de Skills.
`execApprovals.agents.allowlist.expected`	Conjunto agregado de padrões de `agents.*.allowlist[]` e entradas opcionais de argPattern	Exigir que a lista de permissões das aprovações corresponda ao conjunto de padrões revisado.

Exemplo: exigir o artefato de aprovações, negar padrões permissivos e permitir apenas a postura revisada de aprovação de execução para agentes selecionados.

{
  "execApprovals": {
    "requireFile": true,
    "defaults": {
      // Modos de segurança: "deny", "allowlist" ou "full".
      // Este padrão permite apenas a postura restritiva "deny".
      "allowSecurity": ["deny"],
    },
  },
  "scopes": {
    "restricted-shell": {
      "agentIds": ["family-agent", "groups-agent"],
      "execApprovals": {
        "agents": {
          // Os agentes selecionados podem usar a postura "allowlist" revisada, mas não "full".
          "allowSecurity": ["allowlist"],
          // false significa que as CLIs de Skills devem constar na allowlist revisada, em vez de
          // serem aprovadas implicitamente por autoAllowSkills.
          "allowAutoAllowSkills": false,
          "allowlist": {
            "expected": [
              // Entrada simples: padrão exato revisado do executável, sem argPattern.
              "travel-hub",
              // Entrada restrita: padrão acompanhado de uma expressão regular revisada para argumentos.
              { "pattern": "calendar-cli", "argPattern": "^sync\\b" },
              "/bin/date",
            ],
          },
        },
      },
    },
  },
}

Perfis de autenticação

Campo da política	Estado observado	Use quando
`auth.profiles.requireMetadata`	Metadados de provedor e modo de `auth.profiles.*`	Exigir chaves de metadados como `provider` e `mode` nos perfis de autenticação da configuração.
`auth.profiles.allowModes`	`auth.profiles.*.mode`	Permitir apenas modos compatíveis de perfil de autenticação, como `api_key`, `aws-sdk`, `oauth` ou `token`.

Metadados de ferramentas

Campo da política	Estado observado	Use quando
`tools.requireMetadata`	Declarações regidas em `TOOLS.md`	Exigir que as ferramentas regidas declarem chaves de metadados como `risk`, `sensitivity` ou `owner`.

Postura das ferramentas

Campo da política	Estado observado	Use quando
`tools.profiles.allow`	`tools.profile` e `agents.list[].tools.profile`	Permitir apenas IDs de perfil de ferramentas, como `minimal`, `messaging` ou `coding`.
`tools.fs.requireWorkspaceOnly`	`tools.fs.workspaceOnly` e substituições de `tools.fs` por agente	Definir como `true` para exigir que a postura da ferramenta de sistema de arquivos fique restrita ao espaço de trabalho.
`tools.exec.allowSecurity`	`tools.exec.security` e segurança de execução por agente	Permitir apenas modos de segurança de execução, como `deny` ou `allowlist`.
`tools.exec.requireAsk`	`tools.exec.ask` e modo de solicitação de execução por agente	Exigir uma postura de aprovação como `always`.
`tools.exec.allowHosts`	`tools.exec.host` e roteamento do host de execução por agente	Permitir apenas modos de roteamento do host de execução, como `sandbox`.
`tools.elevated.allow`	`tools.elevated.enabled` e postura elevada por agente	Definir como `false` para exigir que o modo elevado de ferramentas permaneça desativado.
`tools.alsoAllow.expected`	`tools.alsoAllow` e `tools.alsoAllow` por agente	Exigir entradas exatas de `alsoAllow` e relatar concessões adicionais de ferramentas ausentes ou inesperadas.
`tools.denyTools`	`tools.deny` e `agents.list[].tools.deny`	Exigir que as listas configuradas de bloqueio de ferramentas incluam IDs ou grupos, como `group:runtime` e `group:fs`.

Executar verificações

Execute verificações exclusivas da política durante a criação:

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

policy check executa apenas o conjunto de verificações da política e emite evidências, constatações e hashes de atestado. As mesmas constatações também aparecem em openclaw doctor --lint quando o Plugin Policy está ativado. Compare um arquivo de política do operador com uma linha de base criada:

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

policy compare compara a sintaxe de um arquivo de política com a sintaxe de outro arquivo de política; ele não inspeciona o estado de execução, as evidências, as credenciais nem os segredos. Ele usa os mesmos metadados de regras que regem as sobreposições por escopo: as allowlists devem permanecer iguais ou mais restritas, as listas de bloqueio devem permanecer iguais ou mais abrangentes, os booleanos obrigatórios devem manter seu valor, as strings ordenadas só podem avançar em direção à extremidade mais restritiva da ordem configurada e as listas exatas devem corresponder. A linha de base pode ser uma política criada pela organização; a política verificada pode adicionar valores mais restritivos ou regras adicionais. Uma regra de nível superior na política verificada pode satisfazer uma regra de linha de base com escopo quando for igualmente ou mais restritiva. Os nomes dos escopos não precisam coincidir entre os arquivos; a comparação é indexada pelo seletor (agentIds/channelIds) e pelo campo. Comparação sem constatações (--json):

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

A saída sem constatações de policy check --json inclui hashes estáveis que um operador ou supervisor pode registrar:

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

Configurar a política

A configuração da política fica em plugins.entries.policy.config.

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

Configuração	Finalidade
`enabled`	Ativar as verificações da política mesmo antes de `policy.jsonc` existir.
`workspaceRepairs`	Permitir que `doctor --fix` edite configurações do espaço de trabalho regidas pela política.
`expectedHash`	Bloqueio opcional por hash para o artefato de política aprovado.
`expectedAttestationHash`	Bloqueio opcional por hash para a última verificação da política aceita sem constatações.
`path`	Local do artefato de política relativo ao espaço de trabalho.

Defina plugins.entries.policy.config.enabled como false para desativar as verificações da política em um espaço de trabalho sem desinstalar o Plugin.

Aceitar o estado da política

Exemplo de saída 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.6-sol",
        "provider": "openai",
        "model": "gpt-5.6-sol",
        "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": []
}

attestation.policy.hash identifica o artefato de regras criado. evidence registra o estado observado do OpenClaw usado pelas verificações, e workspace.hash identifica essa carga de evidências. findingsHash identifica o conjunto exato de constatações. checkedAt registra quando a verificação foi executada. attestationHash identifica a declaração estável (hash da política, hash das evidências, hash das constatações e estado sem/com constatações) e exclui deliberadamente checkedAt, portanto o mesmo estado da política sempre produz o mesmo hash de atestado. Juntos, esses quatro valores formam a tupla de auditoria de uma verificação da política. Se um Gateway ou supervisor usar a política para bloquear, aprovar ou anotar uma ação de execução, ele deverá registrar o hash de atestado da última verificação sem constatações. checkedAt permanece na saída JSON para os logs de auditoria, mas não faz parte do hash estável. Ciclo de vida para aceitar o estado da política:

Crie ou revise policy.jsonc.
Execute openclaw policy check --json.
Se não houver constatações, registre attestation.policy.hash como expectedHash.
Registre attestation.attestationHash como expectedAttestationHash.
Execute novamente openclaw doctor --lint na CI ou nos controles de lançamento.

Se as regras de política mudarem intencionalmente, atualize ambos os hashes aceitos com base em uma verificação limpa. Se apenas as configurações do espaço de trabalho mudarem (a política permanecer igual), normalmente apenas expectedAttestationHash será alterado. Ativar ou atualizar as regras de agents.workspace adiciona evidências de agentWorkspace ao hash do espaço de trabalho e ao hash de atestação; revise as novas evidências e atualize os hashes de atestação aceitos após a ativação. Ativar ou atualizar as regras de postura das ferramentas adiciona evidências de toolPosture da mesma forma. openclaw policy watch executa novamente a verificação e informa quando as evidências atuais deixam de corresponder a expectedAttestationHash:

openclaw policy watch --json

Use --once em CI ou scripts que precisem de uma única avaliação de desvio. Sem --once, por padrão, ele consulta a cada dois segundos; use --interval-ms para alterar o intervalo.

Constatações

ID da verificação	Constatação
`policy/policy-jsonc-missing`	A política está ativada, mas `policy.jsonc` está ausente.
`policy/policy-jsonc-invalid`	Não é possível analisar a política ou ela contém entradas de regras malformadas.
`policy/policy-hash-mismatch`	A política não corresponde ao `expectedHash` configurado.
`policy/attestation-hash-mismatch`	As evidências atuais da política deixaram de corresponder à atestação aceita.
`policy/policy-conformance-invalid`	Um arquivo de política de referência ou verificado tem uma sintaxe de comparação inválida.
`policy/policy-conformance-missing`	Um arquivo de política verificado não contém uma regra exigida pelo arquivo de política de referência.
`policy/policy-conformance-weaker`	Um arquivo de política verificado tem um valor menos restritivo que o arquivo de política de referência.
`policy/channels-denied-provider`	Um canal ativado corresponde a uma regra de negação de canal.
`policy/mcp-denied-server`	Um servidor MCP configurado é negado pela política.
`policy/mcp-unapproved-server`	Um servidor MCP configurado não está na lista de permissões.
`policy/models-denied-provider`	Um provedor de modelos ou uma referência de modelo configurada usa um provedor negado.
`policy/models-unapproved-provider`	Um provedor de modelos ou uma referência de modelo configurada não está na lista de permissões.
`policy/network-private-access-enabled`	Uma válvula de escape de SSRF para redes privadas está ativada quando a política a nega.
`policy/ingress-dm-policy-unapproved`	Uma política de mensagens diretas de canal não está na lista de permissões da política.
`policy/ingress-dm-scope-unapproved`	`session.dmScope` não corresponde ao escopo de isolamento de mensagens diretas exigido pela política.
`policy/ingress-open-groups-denied`	Uma política de grupo de canal é `open` enquanto a política nega a entrada de grupos abertos.
`policy/ingress-group-mention-required`	Uma entrada de canal ou grupo desativa os controles de menção enquanto a política os exige.
`policy/gateway-non-loopback-bind`	A postura de vinculação do Gateway permite exposição fora de local loopback quando a política a nega.
`policy/gateway-auth-disabled`	A autenticação do Gateway está desativada quando a política exige autenticação.
`policy/gateway-rate-limit-missing`	A postura de limitação de taxa da autenticação do Gateway não é explícita quando a política a exige.
`policy/gateway-control-ui-insecure`	As opções de exposição insegura da interface de controle do Gateway estão ativadas.
`policy/gateway-tailscale-funnel`	A exposição do Gateway pelo Tailscale Funnel está ativada quando a política a nega.
`policy/gateway-remote-enabled`	O modo remoto do Gateway está ativo quando a política o nega.
`policy/gateway-http-endpoint-enabled`	Um endpoint da API HTTP do Gateway está ativado, embora seja negado pela política.
`policy/gateway-http-url-fetch-unrestricted`	A entrada de busca de URL por HTTP do Gateway não tem uma lista de URLs permitidas obrigatória.
`policy/gateway-node-command-denied`	Um comando de Node negado pela política não está negado na configuração do OpenClaw.
`policy/agents-workspace-access-denied`	O modo de sandbox do agente ou o acesso ao espaço de trabalho não está na lista de permissões da política.
`policy/agents-tool-not-denied`	A configuração de um agente ou a configuração padrão não nega uma ferramenta cuja negação é exigida pela política.
`policy/tools-profile-unapproved`	Um perfil de ferramentas global ou por agente configurado não está na lista de permissões.
`policy/tools-fs-workspace-only-required`	As ferramentas do sistema de arquivos não estão configuradas com uma postura de caminhos restrita ao espaço de trabalho.
`policy/tools-exec-security-unapproved`	O modo de segurança de execução não está na lista de permissões da política.
`policy/tools-exec-ask-unapproved`	O modo de solicitação de execução não está na lista de permissões da política.
`policy/tools-exec-host-unapproved`	O roteamento de host de execução não está na lista de permissões da política.
`policy/tools-elevated-enabled`	O modo elevado de ferramentas está ativado quando a política o nega.
`policy/tools-also-allow-missing`	Uma lista `alsoAllow` configurada não contém uma entrada exigida pela política.
`policy/tools-also-allow-unexpected`	Uma lista `alsoAllow` configurada contém uma entrada não esperada pela política.
`policy/tools-required-deny-missing`	Uma lista global ou por agente de ferramentas negadas não inclui uma ferramenta cuja negação é obrigatória.
`policy/sandbox-mode-unapproved`	O modo de sandbox não está na lista de permissões da política.
`policy/sandbox-backend-unapproved`	O backend de sandbox não está na lista de permissões da política.
`policy/sandbox-container-posture-unobservable`	Uma regra de postura de contêiner está ativada para um backend que não consegue observá-la.
`policy/sandbox-container-host-network-denied`	Um sandbox ou navegador baseado em contêiner usa o modo de rede do host.
`policy/sandbox-container-namespace-join-denied`	Um sandbox ou navegador baseado em contêiner ingressa no namespace de outro contêiner.
`policy/sandbox-container-mount-mode-required`	Uma montagem de sandbox ou navegador baseada em contêiner não é somente leitura.
`policy/sandbox-container-runtime-socket-mount`	Uma montagem de sandbox ou navegador baseada em contêiner expõe o soquete do runtime de contêiner.
`policy/sandbox-container-unconfined-profile`	O perfil do sandbox de contêiner não está confinado quando a política nega essa condição.
`policy/sandbox-browser-cdp-source-range-missing`	O intervalo de origem CDP do navegador no sandbox está ausente quando a política exige um.
`policy/data-handling-redaction-disabled`	A redação de dados sensíveis nos logs está desativada quando a política a exige.
`policy/data-handling-telemetry-content-capture`	A captura de conteúdo de telemetria está ativada quando a política a nega.
`policy/data-handling-session-retention-not-enforced`	A manutenção da retenção de sessões não é aplicada quando a política a exige.
`policy/data-handling-session-transcript-memory-enabled`	A indexação na memória das transcrições de sessão está ativada quando a política a nega.
`policy/secrets-unmanaged-provider`	Uma SecretRef da configuração referencia um provedor não declarado em `secrets.providers`.
`policy/secrets-denied-provider-source`	Um provedor de segredos da configuração ou uma SecretRef usa uma origem negada pela política.
`policy/secrets-insecure-provider`	Um provedor de segredos adota uma postura insegura quando a política a nega.
`policy/auth-profile-invalid-metadata`	Um perfil de autenticação da configuração não contém metadados válidos de provedor ou modo.
`policy/auth-profile-unapproved-mode`	O modo de um perfil de autenticação da configuração não está na lista de permissões da política.
`policy/exec-approvals-missing`	A política exige `exec-approvals.json`, mas o artefato está ausente.
`policy/exec-approvals-invalid`	Não é possível analisar o artefato de aprovações de execução configurado.
`policy/exec-approvals-default-security-unapproved`	Os padrões de aprovação de execução usam um modo de segurança que não está na lista de permissões da política.
`policy/exec-approvals-agent-security-unapproved`	O modo de segurança efetivo de aprovação de execução por agente não está na lista de permissões.
`policy/exec-approvals-auto-allow-skills-enabled`	Um agente de aprovação de execução permite implicitamente e de forma automática CLIs de Skills quando a política nega isso.
`policy/exec-approvals-allowlist-missing`	A lista de permissões de aprovações não contém um padrão exigido pela política.
`policy/exec-approvals-allowlist-unexpected`	A lista de permissões de aprovações contém um padrão não esperado pela política.
`policy/tools-missing-risk-level`	Uma declaração de ferramenta regida não contém metadados de risco.
`policy/tools-unknown-risk-level`	Uma declaração de ferramenta regida usa um valor de risco desconhecido.
`policy/tools-missing-sensitivity-token`	Uma declaração de ferramenta regida não contém metadados de sensibilidade.
`policy/tools-missing-owner`	Uma declaração de ferramenta regida não contém metadados de proprietário.
`policy/tools-unknown-sensitivity-token`	Uma declaração de ferramenta regida usa um valor de sensibilidade desconhecido.

Uma constatação pode incluir tanto target (o item observado no espaço de trabalho que não está em conformidade) quanto requirement (a regra definida que originou a constatação). Atualmente, ambos são strings de endereço oc://, mas os nomes dos campos descrevem a função na política, e não o formato do endereço. Exemplos de constatações:

{
  "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."
}

{
  "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"
}

{
  "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"
}

{
  "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"
}

{
  "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"
}

{
  "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"
}

{
  "checkId": "policy/gateway-node-command-denied",
  "severity": "error",
  "message": "Gateway node command 'system.run' is denied by policy but not denied by OpenClaw config.",
  "source": "policy",
  "path": "openclaw config",
  "ocPath": "oc://openclaw.config/gateway/nodes/denyCommands",
  "target": "oc://openclaw.config/gateway/nodes/denyCommands",
  "requirement": "oc://policy.jsonc/gateway/nodes/denyCommands",
  "fixHint": "Add 'system.run' to gateway.nodes.denyCommands or update policy after review."
}

{
  "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"
}

Reparo

doctor --lint e policy check são somente leitura. doctor --fix edita as configurações do espaço de trabalho gerenciadas por política somente quando workspaceRepairs está explicitamente habilitado; caso contrário, as verificações informam o que reparariam e deixam as configurações inalteradas. Nesta versão, o reparo pode desabilitar canais negados por channels.denyRules e aplicar os reparos automáticos de restrição listados abaixo. Habilite workspaceRepairs somente depois que o arquivo de política tiver sido revisado, pois uma regra válida pode alterar a configuração do espaço de trabalho:

definir tools.elevated.enabled=false quando uma política global proíbe ferramentas elevadas
adicionar IDs ausentes de ferramentas cuja negação é obrigatória a tools.deny ou agents.list[].tools.deny quando a política exige que essas ferramentas sejam negadas
definir opções inseguras de gateway.controlUi.* como false
definir gateway.mode=local quando a política nega o modo remoto do Gateway
definir os caminhos informados de gateway.http.endpoints.*.enabled como false quando a política nega endpoints da API HTTP do Gateway
definir os caminhos informados de groupPolicy da entrada do canal como allowlist quando a política nega a entrada aberta de grupos
definir os caminhos informados de requireMention da entrada do canal como true quando a política exige menções em grupos
definir logging.redactSensitive=tools quando a política exige a ocultação de dados sensíveis nos logs
definir diagnostics.otel.captureContent=false, ou diagnostics.otel.captureContent.enabled=false para configurações de captura de telemetria no formato de objeto, quando a política nega a captura de conteúdo de telemetria

Os reparos com escopo para ferramentas elevadas são somente de detecção. Os reparos com escopo para tratamento de dados também são ignorados quando a constatação informa uma configuração compartilhada de logs ou telemetria, pois alterar a configuração compartilhada afetaria mais do que o alvo da política com escopo. Os reparos com escopo para negação obrigatória são ignorados quando a constatação informa tools.deny raiz herdado, pois adicionar a ferramenta obrigatória à configuração raiz afetaria mais do que o alvo da política com escopo. Os reparos de negação obrigatória locais do agente podem atualizar o caminho informado de agents.list[].tools.deny. Os reparos com escopo da entrada do canal são ignorados quando a constatação informa channels.defaults.* herdado, pois alterar o padrão compartilhado do canal afetaria mais do que o alvo da política com escopo. As constatações de lista de permissões para busca de URLs HTTP do Gateway permanecem manuais, pois o reparo automático não pode escolher os valores corretos da lista de permissões de URLs do endpoint. As constatações de vinculação e de comandos de Node do Gateway continuam exigindo revisão. Quando policy/gateway-non-loopback-bind ou policy/gateway-node-command-denied podem ser mapeadas para um caminho de configuração, doctor --fix informa a alteração proposta de gateway.bind ou gateway.nodes.denyCommands como uma orientação de prévia ignorada. Ele não aplica a alteração, e a constatação não é considerada reparada até que um operador revise e atualize a configuração ou a política.

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

Códigos de saída

Comando	`0`	`1`	`2`
`policy check`	Nenhuma constatação no limite.	Uma ou mais constatações atingiram o limite.	Falha de argumento ou de execução.
`policy compare`	O arquivo de política é pelo menos tão rigoroso quanto a linha de base.	O arquivo de política é inválido, está ausente ou é menos rigoroso que as regras da linha de base.	Falha de argumento ou de execução.
`policy watch`	Nenhuma constatação, e o hash aceito está atualizado.	Existem constatações ou a atestação aceita está desatualizada.	Falha de argumento ou de execução.

CLI commands

RPC and API

Codex harness

Plugin reference

Plugin SDK reference

Plugin maintainer reference

Templates

Technical reference

Concept internals

Project

Contributing

Política

`openclaw policy`

Início rápido

Referência das regras de política

Sobreposições com escopo

Canais

Servidores MCP

Provedores de modelos

Rede

Entrada e acesso a canais

Gateway

Espaço de trabalho do agente

Postura do sandbox

Tratamento de dados

Segredos

Aprovações de execução

Perfis de autenticação

Metadados de ferramentas

Postura das ferramentas

Executar verificações

Configurar a política

Aceitar o estado da política

Constatações

Reparo

Códigos de saída

Relacionado

​openclaw policy

​Início rápido

​Referência das regras de política

​Sobreposições com escopo

​Canais

​Servidores MCP

​Provedores de modelos

​Rede

​Entrada e acesso a canais

​Gateway

​Espaço de trabalho do agente

​Postura do sandbox

​Tratamento de dados

​Segredos

​Aprovações de execução

​Perfis de autenticação

​Metadados de ferramentas

​Postura das ferramentas

​Executar verificações

​Configurar a política

​Aceitar o estado da política

​Constatações

​Reparo

​Códigos de saída

​Relacionado

`openclaw policy`

Início rápido

Referência das regras de política

Sobreposições com escopo

Canais

Servidores MCP

Provedores de modelos

Rede

Entrada e acesso a canais

Gateway

Espaço de trabalho do agente

Postura do sandbox

Tratamento de dados

Segredos

Aprovações de execução

Perfis de autenticação

Metadados de ferramentas

Postura das ferramentas

Executar verificações

Configurar a política

Aceitar o estado da política

Constatações

Reparo

Códigos de saída

Relacionado