Escopos de operador do OpenClaw

Todo cliente WebSocket do gateway se conecta com um papel, operator ou node, e todo método de operador verifica em seguida um escopo. A página de escopos é o mapa dessa segunda barreira: o que cada escopo significa, como os papéis nomeados os limitam, como uma identidade verificada os obtém e por que aprovar o acesso de outra pessoa nunca concede mais do que você mesmo possui. Ela também deixa explícito que nada disso é isolamento entre locatários.

Papéis e níveis de escopo

• operator é o papel de plano de controle para a CLI, a Control UI, a automação e os auxiliares confiáveis, e node, o papel de host de capacidades para hosts macOS, iOS, Android e sem interface gráfica que expõem comandos por meio de node.invoke; os métodos RPC de operador exigem o papel operator, e os métodos originados em nós, o papel node.
• operator.read cobre status, listas, catálogo, logs, leituras de sessão e diagnósticos de auditoria retidos; operator.write cobre o envio de mensagens, a invocação de ferramentas, as configurações de talk e de voz e a retransmissão de comandos de nó, e também satisfaz read; operator.admin satisfaz todos os escopos de operador e é exigido para alterar a configuração, para atualizações, hooks nativos, namespaces reservados e aprovações de alto risco.
• operator.pairing gerencia o pareamento de dispositivos e de nós, operator.approvals, as APIs de aprovação de execução e de plugins, operator.questions, as perguntas interativas, operator.talk cria, direciona e encerra sessões Talk sem acesso geral de escrita (write também o satisfaz) e operator.talk.secrets lê a configuração de Talk com os segredos; escopos futuros desconhecidos exigem correspondência exata, a menos que quem chama já tenha admin.
• O gerenciamento da conexão pessoal com o GitHub é a única exceção, restrita à própria pessoa, ao comportamento somente leitura: ele exige operator.read mais o perfil durável autenticado exato, então uma pessoa só pode conectar, consultar ou desconectar a própria conta, enquanto as alterações do GitHub no nível do sistema e por agente continuam exigindo admin, e a publicação continua exigindo write mais a autorização de sessão.

Os escopos de operador controlam o que um cliente do Gateway pode fazer depois de se autenticar.

Papéis nomeados e concessões por identidade

Gateways de equipe vinculam perfis duráveis autenticados a papéis nomeados em gateway.roles, cada um combinando quatro políticas fechadas: o acesso às sessões de outras pessoas (none, view, suggest ou write), os agentes disponíveis para criação de sessões e execuções (uma lista, um asterisco ou um array vazio), um conjunto máximo de escopos e se novas sessões exigem sandbox. users.setRole atribui um papel e encerra imediatamente as conexões desse perfil, gateway.roles.default passa a ser obrigatório assim que existem papéis, e quando há papéis configurados os operadores autenticados por identidade deixam de receber tokens de dispositivo ou de bootstrap reutilizáveis, porque esses tokens não estão vinculados a uma pessoa. Uma sandbox obrigatória é isolada por criador da sessão, reduz um espaço de trabalho de leitura e escrita a somente leitura com um aviso, é carimbada de forma imutável com o criador antes da primeira execução, é herdada pelos filhos delegados, nunca recorre ao gateway nem a um nó e não pode ser contornada pelo modo elevated, por substituições do host de exec nem por destinos de host configurados. Em seguida, gateway.auth.identityScopes concede escopos a identidades verificadas vindas da autenticação por proxy confiável ou do Tailscale WhoIs, com as chaves de e-mail comparadas sem diferenciar maiúsculas de minúsculas; conexões por token, por senha e sem autenticação não carregam identidade e não recebem concessão, e conexões de nó nunca recebem.

A barreira do método e o que vem depois

• Cada RPC tem um escopo de método de privilégio mínimo, derivado antes do despacho: agent exige write para turnos comuns e admin para os comandos de ciclo de vida new ou reset; node.invoke exige write para a retransmissão comum e admin ao retransmitir para um nó o proxy de navegador, a listagem de diretórios ou o upload de terminal; sessions.create exige write para a criação comum e admin para sessões incognito ou qualquer execNode; o despacho e a movimentação de sessão derivam o escopo do destino, write para dispositivos e admin para perfis.
• Os handlers aplicam então verificações mais rígidas sobre o objeto concreto: device.pair.approve é acessível com pairing, mas aprovar um dispositivo de operador só pode emitir ou preservar escopos que quem chama já possui, node.pair.approve deriva escopos extras dos comandos declarados pelo nó pendente (write para comandos comuns, admin para system.run, proxy de navegador, listagem de diretórios ou comandos de aprovação de execução), e os comandos de chat config set e unset exigem admin além do envio de chat.
• A autoridade da conexão é resolvida nesta ordem: primeiro o cabeçalho x-openclaw-scopes limita as solicitações de registro ou de upgrade de dispositivo, uma concessão por identidade correspondente no lado do servidor é unida ao conjunto, depois o cabeçalho limita a união final (ausente significa sem limite, presente mas vazio significa nenhum escopo), e um papel nomeado efetivo faz a interseção do resultado com o seu teto; o resultado alimenta tanto hello.auth.scopes quanto a autorização de métodos.

Pareamento no OpenClaw é onde essas aprovações são registradas, e controles de segurança do gateway do OpenClaw, o conjunto mais amplo de controles ao qual os escopos pertencem.

O que os escopos não são

A página repete uma fronteira em vários lugares: escopos são uma proteção do plano de controle dentro de um único domínio de operador de gateway confiável, não isolamento entre locatários hostis. Papéis nomeados organizam a colaboração dentro desse domínio; os métodos de auditoria de diagnóstico continuam sendo superfícies de leitura do domínio compartilhado, não filtradas pelo papel de sessão; operator.write ainda autoriza a invocação de ferramentas e a retransmissão de nós em todo o gateway; e a autenticação por token ou senha de segredo compartilhado é tratada como acesso de operador confiável, que restaura o conjunto completo de escopos padrão nas superfícies compatíveis com OpenAI, na rota de invocação de ferramentas e nos endpoints de histórico de sessão, mesmo quando quem chama declara escopos mais restritos. Para uma separação forte entre pessoas, equipes ou máquinas, a resposta são gateways separados, sob usuários do sistema operacional ou hosts separados. A sandbox do OpenClaw explicada explica a sandbox por criador que um papel pode exigir, e a API HTTP compatível com OpenAI do OpenClaw, a superfície HTTP em que a regra do segredo compartilhado se aplica.

Na Diali

Na Diali, cada cliente roda o próprio gateway, que é a separação que a documentação recomenda, com a configuração do motor gerada a partir do painel e substituída a cada versão. OpenClaw hospedado na Diali descreve o assistente hospedado, e a segurança na Diali, a fronteira em torno de cada motor.

• Write implica read e talk; admin implica tudo.
• A aprovação nunca emite escopos que o aprovador não tem.
• Escopos são uma proteção, não isolamento entre locatários; gateways separados, sim.