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
openclaw plugins enable policyO 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.bindenquanto associações que não sejam local loopback são negadas significa que você aceita o padrão do runtime; definagateway.bind: "loopback"para obter conformidade estrita. - Para um agente somente leitura, defina o
modedo sandbox comoallounon-mainnos padrões ou no agente aplicável e definaworkspaceAccesscomononeouro. Um modo de sandbox ausente ou definido comooffnão atende a uma política somente leitura. agents.workspace.denyToolsaceitaexec,process,write,edit,apply_patch. Os grupos de negação de ferramentas da configuraçãogroup:fs(alteração de arquivos) egroup:runtime(shell/processo) atendem à postura equivalente.- As verificações de aprovações de execução leem o artefato ativo
exec-approvals.jsonsomente quando há uma regraexecApprovals; 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 checkopenclaw policy check --jsonopenclaw policy check --severity-min errorpolicy 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.jsoncopenclaw policy compare --baseline official.policy.jsonc --policy policy.jsonc --jsonpolicy 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.hashcomoexpectedHash. - Registre
attestation.attestationHashcomoexpectedAttestationHash. - Execute novamente
openclaw doctor --lintna 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 --jsonUse --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=falsequando uma política global proíbe ferramentas elevadas - adicionar IDs ausentes de ferramentas cuja negação é obrigatória a
tools.denyouagents.list[].tools.denyquando a política exige que essas ferramentas sejam negadas - definir opções inseguras de
gateway.controlUi.*comofalse - definir
gateway.mode=localquando a política nega o modo remoto do Gateway - definir os caminhos informados de
gateway.http.endpoints.*.enabledcomofalsequando a política nega endpoints da API HTTP do Gateway - definir os caminhos informados de
groupPolicyda entrada do canal comoallowlistquando a política nega a entrada aberta de grupos - definir os caminhos informados de
requireMentionda entrada do canal comotruequando a política exige menções em grupos - definir
logging.redactSensitive=toolsquando a política exige a ocultação de dados sensíveis nos logs - definir
diagnostics.otel.captureContent=false, oudiagnostics.otel.captureContent.enabled=falsepara 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. |