Claw3D

Um espaço de trabalho 3D para agentes de IA.

Projeto não oficial: Claw3D é um projeto independente da comunidade e não é afiliado, endossado ou mantido pela equipe do OpenClaw. OpenClaw é um projeto separado, e este repositório não é o repositório oficial do OpenClaw.

O Claw3D transforma a automação de IA em um local de trabalho visual onde os agentes colaboram, revisam código, executam testes, treinam habilidades e executam tarefas dentro de um ambiente 3D compartilhado.

Criado e mantido por LukeTheDev. Siga no X: @iamlukethedev.

Pense nisso como:

Um escritório para sua equipe de IA.

O que você pode fazer com o Claw3D

• Assista seus agentes de IA trabalhando em tempo real • Realize standups com agentes conectados ao GitHub e Jira • Revise pull requests de dentro do escritório • Monitore pipelines e logs de QA • Treine agentes na academia para desenvolver novas habilidades • Redefina sessões e limpe o contexto com o sistema de zelador

Em vez de gerenciar a automação por meio de painéis e logs…

Você caminha pelo seu local de trabalho de IA.

Visão · Arquitetura · Contribuição · Segurança

O que é o Claw3D

O Claw3D é a camada de visualização e interação.

Hoje ele pode ser utilizado sobre:

• OpenClaw por meio do fluxo de gateway existente
• Hermes por meio do adaptador WebSocket integrado
• um provedor de runtime custom via HTTP direto para pilhas baseadas em orquestradores
• um gateway de demonstração integrado para exploração do escritório sem um framework de agentes real

Em termos práticos, este aplicativo oferece:

• um ambiente de escritório retrô em /office onde os agentes aparecem como trabalhadores se movendo em um mundo 3D compartilhado
• uma superfície em /office/builder para editar e publicar layouts de escritório
• uma arquitetura focada no gateway que mantém o estado do runtime no backend conectado, enquanto o Studio armazena as preferências locais de interface
• uma estrutura de runtime neutra em relação ao backend dentro do Studio, para que provedores adicionais possam ser integrados sem reescrever toda a interface

Este repositório não constrói os runtimes de origem. Ele é o frontend, o Studio e a camada de adaptador/proxy que se conecta a um runtime que fala o protocolo de gateway Claw3D.

Por que ele existe

Os sistemas de IA estão se tornando mais capazes, mas seu trabalho geralmente ainda está escondido atrás de logs, saídas de terminal e painéis.

O Claw3D existe para tornar os sistemas de agentes visíveis:

• inspecionar o que os agentes estão fazendo em tempo real
• monitorar execuções, aprovações, histórico e atividade de um só lugar
• interagir com agentes por meio de chat e superfícies de interface imersivas
• avançar para um mundo onde os sistemas de IA sejam compreensíveis através do espaço, movimento e presença

Para a direção geral do projeto, consulte VISION.md.

O que existe hoje

O aplicativo atual já inclui uma superfície substancial do Claw3D:

• Gerenciamento de equipe e chat do agente com atualizações de runtime transmitidas do gateway.
• Criação de agentes, configurações, controles de sessão, aprovações e edição de configuração baseada em gateway.
• Um escritório retrô 3D com mesas, salas, navegação, animações e avisos de atividade baseados em eventos.
• Espaços operacionais imersivos para standups, fluxos de revisão do GitHub, análises e monitoramento do sistema.
• Persistência local no Studio para detalhes de conexão de gateway, preferências de agentes focados, atribuições de mesa, estado do escritório e configurações de interface relacionadas.
• Um proxy WebSocket personalizado de mesma origem para que o navegador se comunique com o Studio, e o Studio com o Gateway OpenClaw original.

Início Rápido

Requisitos:

• Node.js 20+ recomendado.
• npm 10+ recomendado.
• Um dos seguintes:
  • uma instalação funcional do OpenClaw com uma URL de Gateway e token acessíveis
  • Hermes com o adaptador incluso
  • o gateway de demonstração integrado para exploração local

Pré-requisito:

• O Claw3D não instala ou constrói o OpenClaw ou Hermes para você.
• Antes de iniciar o Claw3D contra um backend real, certifique-se de que o runtime escolhido já esteja em execução e que você saiba a URL do gateway e o token que o Studio deve usar.
• Para uma demonstração de escritório local sem framework, execute o gateway de demonstração incluso.
• Se você precisar de um guia completo de configuração entre máquinas (OpenClaw + Tailscale + Claw3D), siga TUTORIAL.md.

Executar a partir do código-fonte:

git clone <url-do-seu-repositorio-publico> claw3d
cd claw3d
npm install
cp .env.example .env
npm run dev

Em seguida, abra http://localhost:3000 e configure a URL do gateway e o token no Studio. O Studio agora também persiste o modo de backend selecionado (OpenClaw, Hermes, Demo ou Custom) e mostra o backend ativo relatado pelo gateway conectado.

Modo de runtime personalizado (Custom)

Se você estiver integrando um runtime baseado em orquestrador por meio da estrutura de provedor custom, inicie seu runtime primeiro e depois o Claw3D:

npm run dev

Em seguida, abra http://localhost:3000, escolha Custom backend e aponte a URL para o seu limite de runtime, por exemplo:

http://127.0.0.1:7770

Expectativas atuais do runtime custom:

• GET /health
• GET /state
• GET /registry
• POST /v1/chat/completions

O navegador não chama esse runtime diretamente. O Claw3D faz o proxy do provedor custom por meio de sua própria rota de mesma origem em /api/runtime/custom, o que evita problemas de CORS no lado do navegador e mantém o transporte do provedor separado do caminho do gateway OpenClaw/Hermes.

Modo de Demonstração (Demo)

Se você quiser apenas ver o escritório e as interações dos agentes sem instalar o OpenClaw ou Hermes:

npm run demo-gateway
npm run dev

Em seguida, conecte o Studio a:

ws://localhost:18789

Isso inicia um gateway local simulado com agentes de demonstração, chat em streaming, prévias de sessão e presença no escritório. Na tela de conexão, escolha Demo backend e conecte-se.

Adaptador Hermes

Se você quiser usar o Hermes em vez do OpenClaw:

npm run hermes-adapter
npm run dev

Consulte docs/hermes-gateway.md para detalhes de configuração e escopo atual.

Para um gateway local na mesma máquina, a URL usual é:

ws://localhost:18789

Na tela de conexão, escolha Hermes backend e conecte-se.

Como ele se conecta

O Claw3D usa dois saltos de rede separados:

1. Navegador -> Studio via HTTP e um WebSocket de mesma origem em /api/gateway/ws.
2. Studio -> Gateway OpenClaw por meio de um segundo WebSocket aberto pelo servidor Studio.

Isso significa que ws://localhost:18789 sempre se refere ao gateway alcançável a partir do host do Studio, não necessariamente do dispositivo do navegador.

Este design mantém as configurações do gateway persistidas no host do Studio e permite que o Studio abra a conexão com o servidor no lado do servidor. A interface atual ainda carrega a URL/token configurados na memória do navegador em tempo de execução, portanto, trate o navegador como parte do limite de confiança ativo.

Configurações Comuns

Gateway local, Studio local

1. Inicie o Studio com npm run dev.
2. Abra http://localhost:3000.
3. Use ws://localhost:18789 e seu token de gateway OpenClaw.

Gateway remoto, Studio local

Use qualquer URL de gateway que sua máquina possa alcançar.

Recomendado com Tailscale:

1. No host do gateway, execute tailscale serve --yes --bg --https 443 http://127.0.0.1:18789.
2. No Studio, use wss://<gateway-host>.ts.net.

Alternativa com SSH:

1. Execute ssh -L 18789:127.0.0.1:18789 usuario@<host-do-gateway>.
2. No Studio, use ws://localhost:18789.

Studio remoto, Gateway remoto

1. Execute o Studio no host remoto.
2. Exponha o Studio em uma rede privada ou via Tailscale.
3. Defina STUDIO_ACCESS_TOKEN se o Studio estiver vinculado a um host público.
4. Configure a URL do gateway e o token dentro do Studio.

Studio na LAN ou Tailscale para outros dispositivos

1. Inicie o Studio com HOST=0.0.0.0 (ou um host específico da LAN/Tailscale).
2. Defina STUDIO_ACCESS_TOKEN antes de expor o Studio além do localhost.
3. Abra o Claw3D a partir do endereço LAN/Tailscale em vez de localhost.
4. Se você estiver se conectando a um gateway OpenClaw remoto, lembre-se de que a aprovação do dispositivo é por navegador/dispositivo. Um novo navegador ainda pode exigir:

openclaw devices approve --latest

Pilha de Tecnologia

• Next.js App Router, React e TypeScript para a aplicação web principal.
• Um servidor Node personalizado para o proxy WebSocket no Studio.
• Three.js, React Three Fiber e Drei para a experiência de escritório 3D.
• Phaser para fluxos de trabalho de construtor de escritório/visualizador e superfícies interativas relacionadas.
• Vitest para testes unitários e Playwright para cobertura de ponta a ponta.

Configuração

Caminhos de tempo de execução importantes:

• Configuração do OpenClaw: ~/.openclaw/openclaw.json
• Configurações do Studio: ~/.openclaw/claw3d/settings.json

Variáveis de ambiente comuns:

• HOST e PORT controlam o endereço de vinculação e a porta do servidor Studio.
• STUDIO_ACCESS_TOKEN protege o Studio ao vinculá-lo a um host público.
• UPSTREAM_ALLOWLIST restringe a quais hosts de gateway o Studio pode fazer proxy. Defina isso em produção.
• CUSTOM_RUNTIME_ALLOWLIST restringe quais hosts /api/runtime/custom podem buscar. Se não for definido, ele usará UPSTREAM_ALLOWLIST.
• NEXT_PUBLIC_GATEWAY_URL fornece a URL padrão do gateway quando as configurações do Studio estão vazias. Nota: esta é uma variável de tempo de construção — as mudanças requerem npm run build para entrar em vigor.
• CLAW3D_GATEWAY_URL e CLAW3D_GATEWAY_TOKEN fornecem uma alternativa em tempo de execução para NEXT_PUBLIC_GATEWAY_URL que entra em vigor no reinício do servidor sem uma reconstrução.
• CLAW3D_GATEWAY_ADAPTER_TYPE pode ser pareado com CLAW3D_GATEWAY_URL para marcar esses padrões como openclaw, hermes, demo ou custom.
• Se CLAW3D_GATEWAY_URL não for definido, o Studio ainda pode apresentar padrões de adaptador Hermes ou demo locais de HERMES_ADAPTER_PORT / DEMO_ADAPTER_PORT.
• Os padrões de arquivo do OpenClaw ainda vêm de ~/.openclaw/openclaw.json quando presentes.
• OPENCLAW_STATE_DIR e OPENCLAW_CONFIG_PATH substituem os caminhos padrão do OpenClaw.
• OPENCLAW_GATEWAY_SSH_TARGET, OPENCLAW_GATEWAY_SSH_USER, OPENCLAW_GATEWAY_SSH_PORT e OPENCLAW_GATEWAY_SSH_STRICT_HOST_KEY_CHECKING suportam operações avançadas no host do gateway via SSH quando necessário.
• ELEVENLABS_API_KEY, ELEVENLABS_VOICE_ID e ELEVENLABS_MODEL_ID ativam a integração de resposta de voz.

Consulte .env.example para o modelo completo de desenvolvimento local.

Scripts

• npm run dev inicia o servidor de desenvolvimento do Studio.
• npm run hermes-adapter inicia o adaptador WebSocket do Hermes.
• npm run demo-gateway inicia o gateway simulado integrado para o modo de demonstração.
• npm run build constrói o aplicativo Next.js de produção.
• npm run start inicia o servidor de produção.
• npm run lint executa o ESLint.
• npm run typecheck executa o TypeScript sem emitir saída.
• npm run test executa testes unitários com o Vitest.
• npm run e2e executa testes do Playwright.
• npm run studio:setup prepara os pré-requisitos comuns do Studio local.
• npm run smoke:dev-server executa uma verificação básica do servidor de desenvolvimento.

Documentação

• VISION.md: direção do projeto e diretrizes de longo prazo.
• ARCHITECTURE.md: limites do sistema, fluxo de dados e principais compensações.
• TUTORIAL.md: configuração detalhada passo a passo para OpenClaw + Tailscale + Claw3D.
• MULTI_AGENT_BETA.md: configuração da versão beta do escritório remoto, modos de conexão e limitações.
• CODE_DOCUMENTATION.md: mapa prático do código, pontos de extensão e ordem de integração de colaboradores.
• CONTRIBUTING.md: fluxo de trabalho local, testes e expectativas de PR.
• SUPPORT.md: onde pedir ajuda e como encaminhar relatórios.
• ROADMAP.md: prioridades de curto prazo e áreas de trabalho amigáveis para colaboradores.
• docs/pi-chat-streaming.md: streaming do runtime do gateway e renderização de transcrição.
• docs/permissions-sandboxing.md: permissões do Studio e comportamento do OpenClaw.
• docs/hermes-gateway.md: configuração do adaptador Hermes, recursos e limitações atuais.

Limitações Atuais

• O escritório retrô imersivo (/office) e o construtor Phaser (/office/builder) são pilhas relacionadas, mas ainda separadas.
• O aplicativo mantém os segredos do gateway fora do armazenamento persistente do navegador, mas o fluxo de conexão atual ainda carrega a URL/token na memória do navegador em tempo de execução.
• A autenticação local do Spotify para o SOUNDCLAW armazena apenas um token de acesso no momento. O tratamento de refresh-token ainda não foi implementado, portanto, a autenticação local do Spotify pode precisar ser repetida após a expiração do token.

Solução de Problemas

Se a interface carregar, mas a Conexão falhar, o problema geralmente está no lado Studio -> Gateway:

• Confirme a URL e o token nas configurações do Studio.
• Erros EPROTO ou wrong version number geralmente significam que wss:// foi usado contra um endpoint sem TLS.
• Erros INVALID_REQUEST mencionando minProtocol ou maxProtocol geralmente significam que o gateway é muito antigo para o protocolo Claw3D v3. Atualize o OpenClaw, use o adaptador Hermes ou execute npm run demo-gateway.
• 401 Studio access token required geralmente significa que o STUDIO_ACCESS_TOKEN está ativado e a requisição não possui o cookie studio_access esperado.
• Se /api/runtime/custom retornar um erro de host bloqueado em produção, defina CUSTOM_RUNTIME_ALLOWLIST ou inclua o host do runtime em UPSTREAM_ALLOWLIST.
• Códigos de erro de proxy úteis incluem studio.gateway_url_missing, studio.gateway_token_missing, studio.upstream_error e studio.upstream_closed.

As instalações de skills do Marketplace agora usam um fluxo de workspace nativo do gateway e não exigem a ativação de SSH na máquina do usuário.

Autenticação do Spotify em localhost

Se você estiver testando o jukebox SOUNDCLAW localmente e o OAuth do Spotify não aceitar seu callback localhost, use uma ponte de callback ngrok:

1. Mantenha o Claw3D rodando localmente em http://localhost:3000.
2. Inicie o ngrok para o servidor Studio local, por exemplo, ngrok http 3000.
3. Na interface de configuração do jukebox, cole sua URL pública do ngrok no campo ngrok Public URL.
4. No painel do desenvolvedor do Spotify, registre https://<seu-host-ngrok>/spotify/callback como a URI de redirecionamento.
5. Conclua o login no Spotify no painel do jukebox.

Como funciona:

• O aplicativo Claw3D principal permanece em localhost, então seu estado de escritório local normal e o estado do agente permanecem intactos.
• O Spotify redireciona para a URL de callback do ngrok.
• A página de callback passa o código de autenticação de volta para a janela aberta do Claw3D local.

Limitação local atual:

• Como apenas o token de acesso do Spotify é armazenado agora, você pode precisar repetir o fluxo de autenticação ngrok quando esse token expirar durante o desenvolvimento local.

Se você usa outras operações avançadas no host do gateway via SSH:

• macOS: ative Ajustes do Sistema -> Geral -> Compartilhamento -> Acesso Remoto e certifique-se de que o usuário de destino seja permitido.
• Windows: ative o recurso opcional OpenSSH Server, inicie o serviço sshd e permita-o no firewall.
• Linux: certifique-se de que o sshd esteja instalado, em execução e acessível a partir da máquina do Studio.

Para conexões SSH de primeira vez, o Claw3D usa StrictHostKeyChecking=accept-new por padrão para que uma nova chave de host possa ser confiada automaticamente. Se você precisar de um comportamento mais rigoroso, defina OPENCLAW_GATEWAY_SSH_STRICT_HOST_KEY_CHECKING=yes, ou defina como no apenas se desejar explicitamente pular as verificações de chave do host.

Contribuição

Mantenha os pull requests focados, execute npm run lint, npm run typecheck e npm run test antes de abrir um PR, e atualize a documentação quando o comportamento ou a arquitetura mudarem.

Diretrizes de Edição com IA

Se você usar o Cursor ou outro fluxo de trabalho assistido por IA, revise as diretrizes do projeto em .cursor/rules/claw3d-project-guardrails.mdc.

Esse arquivo de regras captura as expectativas de edição compartilhadas para este repositório, incluindo o limite Claw3D-vs-OpenClaw, convenções de posicionamento de código, distinções de pilha do escritório e expectativas de atualização de documentação/testes.

As expectativas da comunidade vivem em CODE_OF_CONDUCT.md. As instruções para relatar problemas de segurança vivem em SECURITY.md.