Painel do Agente OpenClaw

Um painel de monitoramento em tempo real, bonito e seguro, para agentes OpenClaw. Acompanhe sessões, monitore o uso da API, visualize custos, gerencie arquivos de memória e mantenha-se atualizado sobre a saúde do sistema — tudo em um só lugar.

📸 Capturas de Tela

Visão Geral	Sessões	Custos

Limites de Taxa	Feed ao Vivo	Logs

✨ Funcionalidades

• 🤖 Gerenciamento de Sessões — Veja todas as sessões dos agentes com status de atividade em tempo real
• 📊 Monitoramento de Limites de Taxa — Acompanhe o uso das APIs Claude e Gemini em janelas contínuas
• 💰 Análise de Custos — Discriminação detalhada de gastos por modelo, sessão e período de tempo
• ⚡ Feed ao Vivo — Fluxo em tempo real de mensagens dos agentes em todas as sessões
• 🧠 Visualizador de Memória — Navegue e leia arquivos de memória do agente (MEMORY.md, HEARTBEAT.md, anotações diárias)
• 📁 Gerenciador de Arquivos — Veja e edite arquivos do workspace, skills e configurações com proteção de segurança
• 📈 Saúde do Sistema — Monitoramento de CPU, RAM, disco, temperatura com sparklines
• 🔄 Controle de Serviços — Ações rápidas para reiniciar OpenClaw, painel ou outros serviços
• 📋 Visualizador de Logs — Logs do sistema em tempo real com atualização automática
• ⏰ Gerenciamento de Cron — Veja, ative/desative e dispare manualmente jobs cron
• 🌐 Integração com Tailscale — Veja status do Tailscale, IP e peers conectados
• 🎯 Mapa de Calor de Atividade — Visualize horários de pico de uso nos últimos 30 dias
• 🔥 Acompanhamento de Sequências — Monitore sequências diárias de atividade
• 🔍 Pesquisa e Filtro de Sessões — Filtre por status, modelo, intervalo de datas com pesquisa ao vivo
• 🎨 Temas Claro/Escuro — Alterne entre modos claro e escuro com preferência persistente
• ⌨️ Atalhos de Teclado — Navegue rapidamente com teclas de atalho (1-7, Espaço, /, Esc, ?)
• 📱 Responsivo para Dispositivos Móveis — Funciona em celulares e tablets
• 🔔 Notificações do Navegador — Seja alertado quando os limites de uso estiverem próximos
• 📊 Visão em Linha do Tempo — Linha do tempo visual da atividade da sessão
• 💾 Atividade do Git — Acompanhe commits recentes em seus repositórios
• 🎛️ Coletor de Uso do Claude — Obtenha dados reais de uso da CLI do Claude Code
• 🔷 Monitoramento de Uso do Gemini — Monitore o uso de modelos Google Gemini com detalhamento por modelo
• 🔀 Alternância de Provedor — Alterne entre uso do Claude e Gemini no cartão de visão geral

🚀 Início Rápido```bash

Clone the repository

git clone https://github.com/tugcantopaloglu/openclaw-dashboard.git cd openclaw-dashboard

Set your OpenClaw workspace path (optional, auto-detects if not set)

export WORKSPACE_DIR=/path/to/your/openclaw/workspace

Start the dashboard

node server.js

Visite `http://localhost:7000` no seu navegador. Na primeira visita, você verá uma **tela de registro** onde cria seu nome de usuário e senha. Após o registro, faça login com suas credenciais.

## 📦 Instalação

### Pré-requisitos

- **Node.js** v18 ou superior (verifique com `node --version`)
- **OpenClaw** instalado e em execução
- **Systemd** (opcional, para instalação do serviço no Linux)

#### Dependências opcionais

| Ferramenta | Necessário para | Instalar |
|------|-------------|---------|
| `jq` | Página de gerenciamento do Docker | `sudo apt install jq` |
| `tmux` | Scraper de uso da CLI do Claude | `sudo apt install tmux` |
| `python3` | Parser de uso da CLI do Claude | Geralmente pré-instalado |
| `docker` | Página de gerenciamento do Docker | [docs.docker.com](https://docs.docker.com/engine/install/) |

### Instalação Manual

1. **Clone o repositório**   ```bash
   git clone https://github.com/tugcantopaloglu/openclaw-dashboard.git
   cd openclaw-dashboard

2. Configurar ambiente (opcional) ```bash export DASHBOARD_PORT=7000 export WORKSPACE_DIR=/path/to/your/workspace export OPENCLAW_DIR=$HOME/.openclaw export OPENCLAW_AGENT=main
   root@kitploit:~

3. Inicie o servidor ```bash node server.js
   root@kitploit:~

O servidor imprimirá: ``` 🚀 Dashboard running on http://localhost:7000 🔑 Recovery token: abc123def456...

**Salve o token de recuperação** — você precisará dele se esquecer sua senha.

4. **Acesse o painel**
Abra `http://localhost:7000` e registre sua conta.

### Serviço Systemd (install.sh)

Para executar o painel como um serviço do sistema com inicialização automática e recuperação de falhas:```bash
sudo ./install.sh

Isto irá:

• Criar /etc/systemd/system/agent-dashboard.service
• Criar configuração de substituição em /etc/systemd/system/agent-dashboard.service.d/override.conf
• Ativar e iniciar o serviço
• Definir o caminho do seu espaço de trabalho e gerar um token de recuperação

Ver registos:```bash journalctl -u agent-dashboard -f

### Docker```bash
# Build
docker build -t openclaw-dashboard .

# Run
docker run -d \
  --name openclaw-dashboard \
  -p 3001:3001 \
  -e WORKSPACE_DIR=/app/workspace \
  -e DASHBOARD_ALLOW_HTTP=true \
  -v ~/.openclaw:/home/node/.openclaw:ro \
  -v ~/.openclaw/workspace:/app/workspace \
  openclaw-dashboard

Para acesso à página de gerenciamento do Docker, passe o Docker socket:```bash docker run -d
--name openclaw-dashboard
-p 3001:3001
-e WORKSPACE_DIR=/app/workspace
-e DASHBOARD_ALLOW_HTTP=true
-v ~/.openclaw:/home/node/.openclaw:ro
-v ~/.openclaw/workspace:/app/workspace
-v /var/run/docker.sock:/var/run/docker.sock:ro
--group-add $(stat -c '%g' /var/run/docker.sock)
openclaw-dashboard

### Variáveis de Ambiente

| Variável | Descrição | Padrão |
|----------|-----------|--------|
| `DASHBOARD_PORT` | Porta do servidor | `7000` |
| `DASHBOARD_TOKEN` | Token de recuperação para redefinição de senha | Gerado automaticamente na inicialização |
| `WORKSPACE_DIR` | Caminho do espaço de trabalho do OpenClaw | `$OPENCLAW_WORKSPACE` ou diretório atual |
| `OPENCLAW_DIR` | Diretório de configuração do OpenClaw | `~/.openclaw` |
| `OPENCLAW_AGENT` | ID do agente a monitorar | `main` |
| `DASHBOARD_ALLOW_HTTP` | Permitir HTTP de IPs não locais | `false` |

**Exemplos:**```bash
# Custom port
DASHBOARD_PORT=8080 node server.js

# Custom recovery token
DASHBOARD_TOKEN=my_secret_token_12345 node server.js

# Different workspace
WORKSPACE_DIR=/mnt/data/openclaw node server.js

🔐 Autenticação

O dashboard usa autenticação por nome de utilizador e palavra-passe com sessões seguras no lado do servidor.

Registo Inicial

1. Visite o URL do dashboard (ex.: http://localhost:7000)
2. Verá um ecrã de registo
3. Escolha um nome de utilizador e uma palavra-passe
4. Clique em Registar
5. Inicie sessão com as suas novas credenciais

Início de Sessão

• Insira o seu nome de utilizador e palavra-passe
• Opcionalmente, marque "Lembrar-me" para permanecer com sessão iniciada por 3 horas (usa localStorage)
• Sem "Lembrar-me", a sua sessão dura apenas até fechar o navegador (usa sessionStorage)

Segurança da Palavra-Passe

• Hash PBKDF2 — 100.000 iterações com SHA-512
• Sal aleatório — Único por palavra-passe
• Sessões no lado do servidor — As palavras-passe nunca são armazenadas no navegador, apenas tokens de sessão
• Comparações seguras contra temporização — Previne ataques de temporização na verificação de palavras-passe

Limitação de Taxa

Para prevenir ataques de força bruta:

• 5 tentativas de início de sessão falhadas → bloqueio suave de 15 minutos
• 20 tentativas de início de sessão falhadas → Bloqueio duro (requer reinício do serviço)
• Os limites de taxa estão na memória e são reiniciados quando o serviço reinicia

🔑 Autenticação Multifator (MFA)

Adicione uma camada extra de segurança com palavras-passe únicas baseadas no tempo (TOTP).

Ativar MFA

1. Inicie sessão no dashboard
2. Vá para a página Segurança (barra lateral)
3. Clique em "Ativar MFA"
4. Aparece um código QR — digitalize-o com a sua aplicação de autenticação:
   • Google Authenticator (iOS, Android)
   • Authy (iOS, Android, Desktop)
   • Microsoft Authenticator (iOS, Android)
   • 1Password, Bitwarden, ou qualquer aplicação compatível com TOTP
5. Insira o código de 6 dígitos mostrado na sua aplicação para verificar
6. MFA está agora ativa! 🎉

Usar MFA

Uma vez ativada, cada início de sessão requer:

1. O seu nome de utilizador e palavra-passe (como de costume)
2. Um código TOTP de 6 dígitos da sua aplicação de autenticação

• Os códigos renovam-se a cada 30 segundos
• O dashboard aceita códigos com tolerância de ±1 janela para desvio de relógio (30 segundos antes/depois)

Desativar MFA

1. Vá para a página Segurança
2. Clique em "Desativar MFA"
3. Insira o seu código TOTP de 6 dígitos atual para confirmar
4. MFA está agora desativada

Repor MFA (se bloqueado)

Se perder o acesso à sua aplicação de autenticação (telefone perdido, aplicação desinstalada, etc.):

1. Faça SSH para o seu servidor
2. Execute este comando para limpar o segredo MFA: ```bash node -e "const fs=require('fs');const c=JSON.parse(fs.readFileSync('/root/clawd/data/credentials.json','utf8'));delete c.mfaSecret;fs.writeFileSync('/root/clawd/data/credentials.json',JSON.stringify(c,null,2));console.log('MFA cleared')"
   root@kitploit:~

3. Reiniciar o dashboard: ```bash systemctl restart agent-dashboard
   root@kitploit:~

4. Faça login apenas com seu nome de usuário e senha
5. Reative o MFA com um novo código QR

Importante: Ajuste o caminho /root/clawd/data/credentials.json se seu workspace estiver em outro local.

🔓 Recuperação de Senha

Esqueceu a senha?

Se você esquecer sua senha:

1. Clique em "Esqueceu a senha?" na tela de login
2. Insira seu token de recuperação (veja "Encontrando seu Token de Recuperação" abaixo)
3. Defina uma nova senha
4. Faça login com sua nova senha

Encontrando seu Token de Recuperação

O token de recuperação (DASHBOARD_TOKEN) é exibido quando o servidor inicia. Você pode encontrá-lo em vários lugares:

Verifique os Logs de Inicialização do Servidor```bash

journalctl -u agent-dashboard | grep "Recovery token"

Saída:

🔑 Recovery token: 3e6b91f352418b486a9aa9d82fbbc1b1

#### Verificar Configuração de Substituição do Systemd```bash
cat /etc/systemd/system/agent-dashboard.service.d/override.conf

Procure por:```ini Environment=DASHBOARD_TOKEN=3e6b91f352418b486a9aa9d82fbbc1b1

#### Verificar Variável de Ambiente
Se você a configurou manualmente:```bash
echo $DASHBOARD_TOKEN

Alterar a Sua Senha

Para alterar sua senha enquanto estiver logado:

1. Acesse a página Segurança
2. Insira sua senha atual
3. Insira sua nova senha
4. Clique em "Alterar Senha"
5. Todas as outras sessões são invalidadas (você precisará fazer login novamente em outro lugar)

Redefinição Completa da Conta (Opção Nuclear)

Se tudo estiver bloqueado e você não conseguir fazer login:

1. Faça SSH no seu servidor
2. Exclua o arquivo de credenciais: ```bash rm /root/clawd/data/credentials.json
   root@kitploit:~

3. Reinicie o dashboard: ```bash systemctl restart agent-dashboard
   root@kitploit:~

4. Acesse o dashboard — a tela de registro aparece
5. Crie uma nova conta do zero

Aviso: Isso exclui seu nome de usuário, senha e configurações de MFA. Os arquivos de memória e logs de auditoria não são afetados.

🛡️ Recursos de Segurança

O dashboard é construído com as melhores práticas de segurança:

• PBKDF2 hashing de senha — 100,000 iterações, SHA-512, salt aleatório
• Comparações seguras contra temporização — Previne ataques de temporização na verificação de token/senha
• Sessões no servidor — Tokens de sessão armazenados na memória, senhas nunca enviadas ao navegador
• Limitação de taxa — Limitador de taxa unificado para tentativas de login (5 soft / 20 hard bloqueio)
• Imposição de HTTPS — HTTP bloqueado exceto de localhost e Tailscale (100.64.0.0/10)
• Cabeçalhos de segurança:
  • HSTS — Forçar HTTPS em visitas futuras
  • CSP — Política de Segurança de Conteúdo (sem scripts inline, mesma origem)
  • X-Frame-Options: DENY — Prevenir clickjacking
  • X-Content-Type-Options: nosniff — Prevenir MIME sniffing
  • X-XSS-Protection: 1; mode=block — Proteção legada contra XSS
• Registro de auditoria — Todos os eventos de autenticação e ações destrutivas registrados em data/audit.log
• CORS — Apenas mesma origem, nenhum curinga (*) permitido
• Validação de entrada:
  • Lista branca de serviços para logs e ações
  • Proteção contra path traversal para acesso a arquivos
  • Limites de tamanho de payload (máx. 1MB)
• Backups automáticos — Arquivos .bak criados antes de sobrescrever arquivos do workspace

🌐 Segurança de Rede

O dashboard é projetado para acesso local ou via Tailscale:

Métodos de Acesso Recomendados

1. Localhost — Acesso da mesma máquina: http://localhost:7000
2. Tailscale — Acesso da sua rede Tailscale: http://100.x.x.x:7000
   • O Tailscale fornece criptografia TLS automática (MagicDNS + HTTPS)
   • Os IPs do Tailscale (100.64.0.0 a 100.127.255.255) estão isentos da imposição de HTTPS
3. Rede local — Acesso da LAN (use HTTPS ou defina DASHBOARD_ALLOW_HTTP=true)

Imposição de HTTPS

Por padrão, o dashboard bloqueia o acesso HTTP de IPs não locais. Exceções:

• Localhost (127.0.0.1, ::1)
• IPs do Tailscale (100.64.0.0/10)

Para outras redes, o dashboard exige HTTPS ou o cabeçalho X-Forwarded-Proto: https (de um proxy reverso).

Para permitir HTTP de todos os IPs (não recomendado):```bash DASHBOARD_ALLOW_HTTP=true node server.js

### Não Expor à Internet Pública

**Este painel NÃO é reforçado para exposição à Internet pública.** Embora tenha autenticação e limitação de taxa, foi concebido para redes privadas. Se precisar de o expor:
- Use um proxy reverso (nginx, Caddy) com HTTPS
- Adicione lista de permissão de IP
- Considere usar VPN (Tailscale, WireGuard) em vez disso

## 🛠️ Resolução de Problemas

### "Demasiadas tentativas falhadas"

**Problema:** Vê "Demasiadas tentativas de login falhadas. Por favor, tente novamente mais tarde."

**Soluções:**
- Aguarde **15 minutos** para o bloqueio temporário expirar
- Reinicie o serviço para limpar os limites de taxa:  ```bash
  systemctl restart agent-dashboard

• Os limites de taxa são mantidos em memória e são redefinidos ao reiniciar

Não consigo entrar após alterar a senha

Problema: Sua senha foi alterada mas você não consegue entrar.

Solução: Use o fluxo "Esqueceu a senha?" com seu token de recuperação para definir uma nova senha.

Código MFA não funciona

Problema: O código TOTP de 6 dígitos é rejeitado.

Soluções:

• Certifique-se de que o relógio do seu telefone está sincronizado:
  • iOS: Ajustes → Geral → Data e Hora → Ajustar Automaticamente
  • Android: Configurações → Sistema → Data e Hora → Data e hora automáticas
• Os códigos TOTP têm tolerância de ±30 segundos para desvios de relógio
• Tente digitar o próximo código (espere 30 segundos para que ele seja atualizado)
• Se ainda falhar, redefina o MFA via SSH (veja a seção "Redefinindo MFA")

Dashboard não carrega

Problema: O navegador mostra uma página em branco ou erro de conexão.

Soluções:

1. Verifique o status do serviço: ```bash systemctl status agent-dashboard
   root@kitploit:~

2. Verificar logs: ```bash journalctl -u agent-dashboard -n 50
   root@kitploit:~

3. Verificar porta: ```bash curl http://localhost:7000/api/auth/status
   root@kitploit:~

Deve retornar: ```json {"authenticated": false, "requiresRegistration": false}

### Erro "HTTPS obrigatório"

**Problema:** O navegador mostra "HTTPS obrigatório. Aceda via localhost, Tailscale, ou ative HTTPS."

**Soluções:**
- Aceder via **localhost**: `http://localhost:7000`
- Aceder via **Tailscale**: `http://100.x.x.x:7000`
- Definir `DASHBOARD_ALLOW_HTTP=true` no ambiente (não recomendado):  ```bash
# Add to /etc/systemd/system/agent-dashboard.service.d/override.conf
Environment=DASHBOARD_ALLOW_HTTP=true

# Reload and restart
systemctl daemon-reload
systemctl restart agent-dashboard

Página em branco após atualização

Problema: O painel mostra uma página em branco após puxar novo código.

Soluções:

• Recarregamento forçado: Ctrl+Shift+R (Windows/Linux) ou Cmd+Shift+R (macOS)
• Limpar cache do navegador para o URL do painel
• Verificar console do navegador (F12 → Aba Console) para erros de JavaScript

📡 Referência da API

O painel expõe uma API REST para acesso programático. Todos os endpoints exigem autenticação via cabeçalho Authorization: Bearer <sessionToken>.

Endpoints Não Autenticados

• GET /api/auth/status — Verificar status de autenticação
• POST /api/auth/login — Fazer login com usuário/senha (+ TOTP se MFA ativado)
• POST /api/auth/register — Registrar uma nova conta (apenas se não existirem credenciais)
• POST /api/auth/reset-password — Redefinir senha com token de recuperação

Endpoints Autenticados

Todos os outros endpoints exigem autenticação:

• GET /api/config — Configuração do painel
• GET /api/sessions — Listar todas as sessões de agente
• GET /api/usage — Dados de uso em janela rolante de 5 horas
• GET /api/costs — Dados de gastos por dia, modelo e sessão
• GET /api/system — Métricas de saúde do sistema
• GET /api/memory-files — Listar arquivos de memória
• GET /api/memory-file?path=<path> — Ler um arquivo de memória
• GET /api/key-files — Listar arquivos do workspace (skills, configurações)
• GET /api/key-file?path=<name> — Ler um arquivo do workspace
• POST /api/key-file — Escrever em um arquivo do workspace (com backup)
• GET /api/crons — Listar tarefas cron
• POST /api/cron/<id>/toggle — Ativar/desativar uma tarefa cron

Para exemplos detalhados de requisição/resposta, consulte a versão anterior deste README ou explore a API na aba Network do navegador.

📂 Arquivos de Dados

O painel armazena dados no diretório do seu workspace:

Estrutura do arquivo de credenciais:```json { "username": "admin", "passwordHash": "pbkdf2_sha512$100000$...", "salt": "...", "mfaSecret": "BASE32SECRET..." // Only if MFA enabled }

## 🔗 Integração OpenClaw

O painel detecta automaticamente:
- **Sessões** de `$OPENCLAW_DIR/agents/$AGENT_ID/sessions/`
- **Tarefas cron** de `$OPENCLAW_DIR/cron/jobs.json`
- **Arquivos de memória** de `$WORKSPACE_DIR/MEMORY.md`, `HEARTBEAT.md` e `memory/*.md`
- **Repositórios Git** de `$WORKSPACE_DIR/projects/*/`
- **Dados de saúde** salvos em `$WORKSPACE_DIR/data/health-history.json`

### Arquivos Necessários

O painel funciona melhor quando estes arquivos existem:
- `$WORKSPACE_DIR/MEMORY.md` - Memória de longo prazo do agente
- `$WORKSPACE_DIR/HEARTBEAT.md` - Lista de tarefas do Heartbeat
- `$WORKSPACE_DIR/memory/YYYY-MM-DD.md` - Notas de memória diárias
- `$WORKSPACE_DIR/scripts/scrape-claude-usage.sh` - Extrator de uso do Claude
- `$WORKSPACE_DIR/scripts/parse-claude-usage.py` - Analisador de uso do Claude
- `$WORKSPACE_DIR/scripts/scrape-gemini-usage.sh` - Extrator de uso do Gemini
- `$WORKSPACE_DIR/scripts/parse-gemini-usage.py` - Analisador de uso do Gemini

## ⌨️ Atalhos de Teclado

| Tecla | Ação |
|-----|--------|
| `1` | Mudar para Visão Geral |
| `2` | Mudar para Sessões |
| `3` | Mudar para Custos |
| `4` | Mudar para Limites de Taxa |
| `5` | Mudar para Memória |
| `6` | Mudar para Arquivos |
| `7` | Mudar para Feed Ao Vivo |
| `8` | Mudar para Registros |
| `9` | Mudar para Segurança |
| `Espaço` | Pausar/Retomar Feed (quando na página de Feed Ao Vivo) |
| `/` | Focar caixa de pesquisa |
| `Esc` | Fechar modais e sobreposições |
| `?` | Mostrar ajuda de atalhos de teclado |

## 🤝 Contribuindo

Contribuições são bem-vindas! Por favor, siga estas diretrizes:

1. **Fork** o repositório
2. **Crie** um branch de funcionalidade (`git checkout -b feature/amazing-feature`)
3. **Faça commit** das suas alterações (`git commit -m 'Adicionar funcionalidade incrível'`)
4. **Envie** para o branch (`git push origin feature/amazing-feature`)
5. **Abra** um Pull Request

### Configuração de Desenvolvimento```bash
git clone https://github.com/tugcantopaloglu/openclaw-dashboard.git
cd openclaw-dashboard
export WORKSPACE_DIR=/path/to/test/workspace
node server.js

O painel não tem etapa de construção — edite server.js ou index.html e recarregue.

Estilo de Código

• Sem comentários no código (autodocumentado)
• Nomes de função breves e diretos

📄 Licença

Licença MIT - veja o arquivo LICENSE para detalhes.

🙏 Agradecimentos

• Construído com Claude Code
• Construído para OpenClaw
• Inspirado por painéis modernos (Grafana, Vercel, Railway)
• Fonte: Inter e JetBrains Mono

📞 Suporte

• Issues: GitHub Issues
• Twitter: @tugcantopaloglu

Feito com ✨ por Tuğcan Topaloğlu