OpenClaw não controla o Windows? Como corrigir CUA, pareamento e computer.act

Uma coisa é instalar o OpenClaw e receber respostas. Outra é pedir para o agente olhar a tela, identificar janelas ou interagir com o mouse e descobrir que ele “não tem acesso ao computador”.

Foi exatamente o que aconteceu durante a configuração de um OpenClaw no Windows 11 com Gateway em WSL2. O terminal funcionava. O agente lia arquivos. O nó Windows aparecia como conectado e aprovado. Mesmo assim, o controle gráfico falhava.

O erro só começou a fazer sentido quando deixamos de tratar “nó conectado” como sinônimo de “nó capaz de controlar o desktop”.

Pareamento, capacidade anunciada, política de ferramenta e execução bem-sucedida são quatro verificações diferentes.

O que é Computer Control no OpenClaw?

A ferramenta computer permite que um agente observe e interaja com uma área de trabalho. O caminho usado no caso estudado é:

Agente OpenClaw
    ↓ ferramenta computer
Gateway (WSL2)
    ↓ node.invoke
Windows CUA Node
    ├── screen.snapshot → observação
    └── computer.act    → ações gráficas

A capacidade screen não significa necessariamente que o nó aceite computer.act. O OpenClaw exige um nó compatível e conectado anunciando screen.snapshot e computer.act para a rota de controle gráfico. A documentação também diferencia o desktop do Gateway do desktop de um nó pareado.

Essa distinção explica por que uma captura feita por um nó Windows podia funcionar enquanto a ferramenta computer do agente ainda reclamava.

1. Confirme as versões antes de mexer nas permissões

Na nossa investigação, a CLI global do Windows estava em 2026.4.22, enquanto o Gateway e o Windows Tray usavam versões da linha 2026.9.x.

O sintoma era enganoso: o comando plugins enable cua-computer parecia concluir, mas a versão antiga dizia que o plugin não existia. O doctor --lint nem sequer era reconhecido.

No Windows:

node -v
npm -v
openclaw --version

No Gateway WSL, execute a CLI instalada na distribuição que realmente hospeda o Gateway. No meu ambiente, ela ficava em um runtime Node próprio; não confunda essa CLI com a que o WSL pode encontrar no PATH do Windows.

Use os requisitos de Node.js da versão exata do OpenClaw. Na versão 2026.9.9, o Node.js 22.14.0 era incompatível; após atualizar para 24.21.0, a instalação do CLI Windows pôde ser concluída.

Não use uma CLI antiga para “corrigir” a configuração escrita por uma versão nova. O formato pode ter mudado. Faça backup e compare o arquivo antes de restaurar qualquer versão anterior.

2. Habilite e valide o plugin no Windows

Para o host Windows que executará o controle gráfico:

openclaw plugins enable cua-computer
openclaw doctor --lint --only cua-computer/driver-artifacts

No caso validado, o segundo comando retornou:

checksRun: 1
findings: []

Esse teste confirma os artefatos do driver, mas não comprova que o nó esteja conectado nem que o agente consiga clicar.

O plugin é experimental no Windows/Linux e usa o SDK CUA empacotado. Não é necessário instalar um executável independente cua-driver para essa integração.

3. Não confunda o nó do aplicativo com o CUA Node

O Gateway chegou a mostrar dois nós Windows:

Nó	O que anunciava
Windows Node do Tray	screen, canvas, system, entre outras
Windows CUA Node	computer, screen, computer.act, screen.snapshot

Ambos podiam estar pareados, mas isso não tornava suas capacidades equivalentes.

Confira os nós no Gateway:

openclaw nodes status
openclaw nodes status --json
openclaw nodes pending

O JSON é mais útil do que a tabela compacta porque permite conferir connected, approvalState e o array commands.

Procure:

{
  "connected": true,
  "approvalState": "approved",
  "commands": [
    "computer.act",
    "screen.snapshot"
  ]
}

Esse é um exemplo parcial, não a estrutura completa retornada pela CLI.

Se a superfície de comandos mudar, pode haver nova aprovação de pareamento. Aprove apenas o nó que você reconhece. Não remova todos os dispositivos pareados para “começar do zero” sem diagnóstico.

4. Rode o CUA na sessão gráfica do Windows

O nó CUA precisa rodar em uma sessão de desktop que possa acessar a interface gráfica. No Windows, um serviço iniciado no contexto errado pode existir como processo e ainda assim não oferecer a experiência desejada.

Para um teste inicial controlado, em um PowerShell normal na sessão do usuário:

Atenção: não use --commands para um nó que precisa de Computer Use. Na versão 2026.9.9, esse parâmetro não apenas limita comandos: ele desabilita o descritor computerUse que a ferramenta computer utiliza para autorizar ações como list_windows. Esse foi o motivo real do erro COMPUTER_CONTRACT_MISMATCH no nosso caso.

O comando de diagnóstico em primeiro plano, somente após revisar as permissões do nó, é:

openclaw node run `
  --host 127.0.0.1 `
  --port 18789 `
  --no-tls `
  --display-name "Windows CUA Node" `
  --all-commands

O --all-commands limpa a allowlist persistida e restaura a superfície padrão de comandos. Isso amplia os comandos anunciados e exige uma revisão de segurança e eventual nova aprovação de pareamento. Não rode esse comando em um nó com privilégios amplos sem configurar antes as aprovações locais de execução e as políticas do Gateway.

O endereço e a porta são exemplos para um Gateway local acessível por loopback. Não copie esses parâmetros para uma conexão remota sem adaptar autenticação, transporte e rede.

O problema de passagem da vírgula em --commands também apareceu durante a investigação, mas corrigi-lo não resolve o Computer Use: mesmo com computer.act,screen.snapshot corretamente separado, o descritor v2 continua ausente por desenho da implementação.

5. Não conclua que o processo travou cedo demais

O nó pode levar algum tempo para inicializar. Em nossos testes, o processo apareceu no Gerenciador de Tarefas, consumiu CPU durante a preparação e só depois anunciou:

advertised commands: computer.act, screen.snapshot
node host gateway connected: ws://127.0.0.1:18789

Antes dessas linhas, o Gateway ainda mostrava o CUA como desconectado. Isso gerou tentativas desnecessárias de reinício.

A regra é observar três sinais:

1. O processo existe?
2. O nó anunciou as capacidades esperadas?
3. O Gateway passou a marcar connected: true?

O primeiro sinal sozinho não resolve o problema. E uma conexão que existiu por poucos segundos não prova estabilidade: consulte o estado novamente após a inicialização.

6. Configure a inicialização automática sem duplicidade

Depois de validar o comando em primeiro plano, o OpenClaw oferece a instalação persistente:

Depois de configurar e revisar as aprovações locais e do Gateway, a reinstalação persistente que remove a allowlist incompatível é:

openclaw node install `
  --force `
  --host 127.0.0.1 `
  --port 18789 `
  --no-tls `
  --display-name "Windows CUA Node" `
  --all-commands

Não execute sem revisão de permissões: essa alteração expõe o conjunto padrão de comandos do nó. O pareamento pode exigir nova aprovação da superfície expandida. gateway.nodes.commands.deny é global, podendo afetar outros nós; já a execução de shell possui controles locais próprios.

Verifique o comando efetivo do serviço:

openclaw node status

No caso real, encontramos uma tarefa agendada do Windows e também um item de inicialização na pasta Startup. Preservamos um backup da entrada redundante e deixamos a tarefa agendada como único mecanismo ativo.

Evite executar manualmente node run e iniciar o serviço ao mesmo tempo sem necessidade. Isso pode criar processos concorrentes e confundir o diagnóstico.

Também não confunda o estado “Ready” de uma tarefa agendada com a situação real do nó: consulte o processo e, principalmente, openclaw nodes status --json no Gateway.

7. A prova definitiva é executar computer.act

O teste que comprovou a rota de baixo nível foi uma chamada direta de computer.act ao ID exato do Windows CUA Node, com a ação somente de leitura list_windows e um executionId UUID.

Resultado observado:

ok: true
payload.ok: true
windows: 21

Isso mostrou que o Gateway conseguia encaminhar a chamada, o nó executava a ação e o driver retornava janelas reais.

Nenhum clique foi necessário para essa validação. É melhor começar com list_windows do que mandar o agente mover o mouse ou digitar em um aplicativo aberto.

O contrato de computer.act exige parâmetros estruturados; não use exemplos inventados de ação como se fossem APIs estáveis. Confira a documentação da versão instalada.

8. A causa raiz do erro COMPUTER_CONTRACT_MISMATCH

A investigação do código-fonte da versão instalada revelou duas condições explícitas:

• Em src/node-host/runtime-manifest.ts, o campo computerUse só entra no manifesto quando não existe commandAllowlist e o nó não é efêmero.
• Em src/node-host/plugin-node-host.ts, o descritor também é omitido quando options.commandAllowlist está definido.

Nosso CUA Node estava instalado com --commands computer.act,screen.snapshot. O resultado era paradoxal: nodes describe mostrava computer.act e screen.snapshot, a chamada direta node.invoke com action=list_windows retornava 21 janelas, mas a ferramenta computer recusava a ação com:

COMPUTER_CONTRACT_MISMATCH:
computer node:<id> does not advertise action list_windows

Isso ocorre porque o contrato de ações v2 não estava anunciado. Não é uma limitação comprovada do Qwen 4B ou 9B. Ambos receberam a mesma incompatibilidade da infraestrutura. A correção foi validada no ambiente estudado: primeiro bloqueamos execução local com security=deny, ask=always e fallback deny; depois reinstalamos o CUA Node com --all-commands. O novo manifesto passou a anunciar computerUse.contractVersion=2 e list_windows, e a ferramenta computer do agente passou a executar com sucesso.

Esse comportamento está documentado na referência oficial do openclaw node: --commands desabilita Computer Use, publicação de ferramentas de plugins, MCP e outras capacidades.

9. O agente ainda pode selecionar o computador errado

Aqui está a descoberta mais importante depois da conexão.

Quando pedimos ao agente Qwen local para listar janelas, ele chegou a afirmar que não havia janelas ou que o Windows Node estava desconectado — mesmo com a chamada direta ao CUA funcionando.

A documentação explica uma causa possível: a ferramenta computer distingue target: "gateway" de target: "node". Quando a seleção é omitida, a política pode tentar o desktop do Gateway ou reutilizar um alvo anterior. Uma rota indisponível não é automaticamente redirecionada para outra máquina.

Portanto, em ambientes com mais de um desktop, indique explicitamente o nó:

Use computer com target=node e selecione
o Windows CUA Node conectado.
Execute somente list_windows.
Não altere a interface.

Mesmo depois de corrigir o contrato, não aceite automaticamente o texto final do modelo. No teste pós-correção, o Qwen 4B chamou computer com sucesso e informou 24 janelas; uma leitura direta imediatamente posterior também retornou 24. Porém, os cinco títulos escolhidos pelo modelo não correspondiam fielmente aos cinco primeiros do payload. O Qwen 9B também teve resultados mistos: uma execução usou a ferramenta corretamente, enquanto outra respondeu CONTAGEM=0 sem chamar ferramenta.

Isso separa duas classes de falha: o COMPUTER_CONTRACT_MISMATCH era infraestrutura e foi resolvido; fidelidade na interpretação do payload continua sendo uma propriedade a medir por modelo e tarefa.

Essa diferença é essencial: sucesso do driver não é sucesso do raciocínio do agente.

10. Segurança: controle gráfico é uma permissão poderosa

Ao habilitar computer.act, você permite ações na sessão do Windows. Isso pode incluir interações com aplicativos autenticados e informações sensíveis visíveis na tela.

Boas práticas:

• habilite apenas o nó reconhecido e mantenha o pareamento aprovado;
• para CUA v2, não use --commands como mecanismo de redução da superfície: ele remove o descritor computerUse; restrinja execução de shell por exec approvals/tool policy e revise separadamente os demais comandos anunciados;
• comece com ações de leitura;
• peça confirmação humana antes de alterações, envios ou operações destrutivas;
• não exponha o Gateway nem a API Ollama à internet sem uma arquitetura de acesso seguro;
• não publique tokens, arquivos openclaw.json, IDs de sessão, screenshots privados ou logs completos em tutoriais;
• use armazenamento de segredos apropriado para credenciais do Gateway.

A documentação ressalta que a autorização do Gateway é o ponto de controle; o driver não substitui as políticas de permissão.

Diagnóstico rápido

Situação	Próxima verificação
screen.snapshot funciona, computer.act não aparece	Plugin, capabilities e pareamento
doctor --lint é desconhecido	Versão da CLI
Nó pareado, mas desconectado	Inicialização, logs e sessão gráfica
Processo usa CPU, sem conexão imediata	Aguardar anúncio das capacidades e conferir Gateway
--commands rejeita IDs	Corrigir sintaxe não basta: essa flag desativa Computer Use
Chamada direta funciona, agente recebe COMPUTER_CONTRACT_MISMATCH	Verificar se --commands suprimiu computerUse
O agente diz que clicou, mas nada mudou	Observação posterior da interface e confirmação de efeito

Conclusão

Conseguimos fazer o OpenClaw reconhecer um CUA Node Windows, endurecer a política local de execução, remover a allowlist incompatível, publicar computerUse v2 e executar list_windows tanto diretamente quanto pela ferramenta computer do agente. O serviço persistente ficou conectado via Scheduled Task e a política local continuou com security=deny.

O próximo desafio não era mais instalação. Era confiabilidade do agente que decide quando, onde e como usar a ferramenta.

É uma diferença que muda completamente a forma de testar agentes locais. Um sistema só está pronto para automação real quando consegue provar não apenas que recebeu uma instrução, mas que executou a ação correta, no alvo correto, com um resultado verificável.

Leituras relacionadas

• O modelo não é o produto: arquitetura, validação e a nova engenharia da IA — por que contratos, validação e ferramentas determinísticas importam mais do que escolher apenas um modelo maior.
• Agentes em produção: migração, permissões e segurança em 2026 — princípios de governança, permissões e observabilidade para agentes que acessam sistemas reais.

CURADORIA SEMANAL

Uma curadoria útil, uma vez por semana

Receba os melhores conteúdos sobre negócios, tecnologia e marketing — sem ruído e sem spam.

Website

Nome opcional Seu melhor e-mail

Quero receber a curadoria semanal e aceito o uso destes dados conforme a Política de Privacidade. Posso cancelar a qualquer momento. Quero receber a curadoria →