🌐 Cette page n'est pas encore traduite en français. Affichage de la référence portugaise (BR). Aidez-nous à traduire.

Agente de IA — RoqueClaw

"Instala o Plex no servidor", "Abre o terminal e me mostra o uso de disco", "Pesquisa hoje no Hacker News e gera um resumo no Notes"

O RoqueClaw (baseado em OpenClaw) é o operador autônomo do seu RoqueOS. Diferente de um chatbot que só responde texto, ele executa ações reais no seu servidor e no seu desktop: instala containers, abre apps, escreve arquivos, dispara notificações, navega na web, executa comandos no terminal.

A diferença prática? Você fala "preciso de um servidor de mídia" e ele instala o Jellyfin, configura, abre no seu navegador e te avisa quando estiver pronto. Em vez de você abrir 5 abas, ler tutorial e seguir 20 passos.

O que ele consegue fazer

🐳 Instalar containers Docker por linguagem natural

você: "Instala o Nextcloud pra mim, com 2GB de RAM"
RoqueClaw: ✓ Instalando nextcloud:latest...
           ✓ Configurando 2GB de RAM e volume persistente
           ✓ Container subiu na porta 8080
           ✓ Abri ele no seu navegador. Login inicial: admin/admin

Por baixo, ele usa o roqueos-cli pré-instalado no servidor (veja seção abaixo) pra chamar a API do RoqueOS Server. Mesma App Store, mesmo catalog, mesmo installApp(appId, config) — só que disparado por linguagem natural ao invés de clique.

💻 Mexer no seu desktop

• Abre apps específicos (Abre o Finder, Abre o VS Code, Abre o navegador em google.com)
• Cria arquivos no Files (Salva esse resumo como /home/user/notes/reuniao.md)
• Envia notificações (Me avisa quando o backup terminar)
• Mostra diálogos (Pergunta pro user se ele aprova esse passo antes de continuar)

🌐 Navegar e automar a web

• Abre Chromium dentro do container isolado (não no seu navegador — segurança)
• Faz scraping, preenche formulários, baixa arquivos
• Tira screenshots pra você acompanhar o progresso visualmente

🤖 Executar tarefas complexas multi-step

Não é um único prompt → uma única resposta. É um loop autônomo:

1. Você descreve o objetivo
2. RoqueClaw planeja os steps
3. Executa cada step (com você vendo ao vivo via VNC)
4. Se algo der errado, ajusta e tenta de novo
5. Ao final, te resume o que foi feito + ações que ele tomou

---

Arquitetura

3 camadas:

• Frontend: Chat + visualização ao vivo do desktop via noVNC
• Backend: Gerencia sessões, containers e o stream de mensagens/steps. Expõe /agent/actions/* endpoints que recebem comandos do CLI e disparam ações no frontend conectado.
• Container RoqueClaw: Ubuntu 22.04 + XFCE + VNC + Chromium + Node.js + OpenClaw + roqueos-cli pré-instalado pra chamar de volta no server.

---

🔧 O CLI roqueos-cli (poder do agente, e também seu)

O roqueos-cli é o canal entre o agente e o RoqueOS Server. Ele está pré-instalado em duas localidades:

Onde	Quem usa
Container do RoqueClaw (/usr/local/bin/roqueos-cli)	O agente chama via subprocess ao executar suas ações
Container do Terminal app (cada usuário do servidor tem um)	Você, via shell, sempre que precisar — mesmo sem o agente

Isso significa que você também pode usar o CLI direto, sem passar pelo agente. Abre o app Terminal, digita roqueos-cli ..., pronto.

Comandos disponíveis

Veja a referência completa rodando roqueos-cli --help no Terminal app — é a fonte da verdade. As 6 ações canônicas:

roqueos-cli notify       <título> <mensagem>      # Notificação no desktop RoqueOS
roqueos-cli open-app     <appId>                  # Abre app (finder, vscode, browser, etc.)
roqueos-cli open-url     <url>                    # Abre URL no Roque Browser
roqueos-cli create-file  <path>                   # Cria arquivo lendo conteúdo do stdin
roqueos-cli run-terminal <comando>                # Executa comando + retorna stdout
roqueos-cli show-dialog  <mensagem> [--type X]    # Modal de confirm/alert/info

Exemplos práticos:

# Enviar notificação pro seu desktop RoqueOS
roqueos-cli notify "Backup concluído" "23 GB sincronizados para Cloudflare R2"

# Abrir um app específico
roqueos-cli open-app finder

# Abrir uma URL no navegador
roqueos-cli open-url "https://github.com/roqueribeiro"

# Criar/escrever um arquivo (lê do stdin)
echo "Anotações da reunião..." | roqueos-cli create-file "/home/user/notes/reuniao.md"

# Executar comando + receber resultado como notificação
roqueos-cli run-terminal "df -h"

# Modal de confirmação (espera resposta do user antes de continuar)
roqueos-cli show-dialog "Apagar 50GB de logs antigos?" --type confirm

Sintaxe usa argumentos posicionais (não flags --title/--message). Se sua versão do CLI for diferente, atualize via apt-get install --reinstall roqueos-cli dentro do container.

Casos de uso reais

Script cron que avisa quando algo acontece:

# Crontab que roda diariamente e te notifica sobre uso de disco
0 9 * * * df -h | grep -E '^/' | awk '$5+0 > 80 {print $6, $5}' | \
  xargs -I {} roqueos-cli notify "Disco quase cheio" "{}"

Workflow de deploy:

# Build script que abre o log no VS Code quando termina
yarn build && roqueos-cli open-app vscode && \
  roqueos-cli notify "Build OK" "Verifique o log em /tmp/build.log"

Integração com outros containers:

# Um job dentro de outro container (ex: Plex transcoding) avisa pro user
roqueos-cli notify "Plex" "Transcode 4K terminou. Filme pronto."

A API HTTP por trás está documentada em 75-agent-module.md (rule interna do server), seção "Actions". Mesmas ações que o frontend usa via WebSocket — notify, open-app, open-url, create-file, run-terminal, show-dialog.

---

Modelos de IA suportados

O RoqueClaw funciona com os principais provedores de LLM:

Provedor	Modelos recomendados	Configuração
OpenAI	GPT-4o, GPT-4-turbo	OPENAI_API_KEY env var no container
Anthropic	Claude 3.5 Sonnet, Claude 4.6 Sonnet	ANTHROPIC_API_KEY env var

A escolha do modelo afeta velocidade e qualidade das ações. Pra automação web complexa, Claude Sonnet 4.6 ou GPT-4o costumam ter melhor controle visual via VNC.

---

Casos de uso reais

Cenário	Tarefa	Resultado
Setup novo servidor	"Instala Plex, qBittorrent e Sonarr, configura eles pra trabalhar juntos"	3 containers up + interconectados em ~3 min
Pesquisa	"Pesquisa os 5 melhores frameworks JS de 2026 e gera um arquivo comparativo no Notes"	Artigo MD salvo em /home/user/notes/ + open no Finder
Diagnóstico	"Verifica por que o servidor tá lento"	Roda top, df, free, docker stats — gera relatório no Notes
Automação	"Baixa o backup do Google Drive de ontem e descompacta em /data"	Login OAuth + download + extract via tar
Desenvolvimento	"Cria um script Python que monitora minha API e avisa se cair"	Script salvo em /home/user/projects/ + cron configurado
Casa inteligente	"Conecta com Home Assistant e me mostra quais luzes estão ligadas"	Lista live + opção de desligar via chat

---

Próximos passos

• Configuração — Como instalar e habilitar o RoqueClaw (flag --with-roqueclaw no installer)
• Como usar — Tutorial passo a passo + boas práticas de prompt + comandos completos do CLI