CLI commands

Política

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

bash
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:

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

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

jsonc
{  "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:

bash
openclaw policy checkopenclaw policy check --jsonopenclaw 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:

bash
openclaw policy compare --baseline official.policy.jsoncopenclaw 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):

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:

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

jsonc
{  "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:

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:

  1. Crie ou revise policy.jsonc.
  2. Execute openclaw policy check --json.
  3. Se não houver constatações, registre attestation.policy.hash como expectedHash.
  4. Registre attestation.attestationHash como expectedAttestationHash.
  5. 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:

bash
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:

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

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

Relacionado

Was this useful?
On this page

On this page