Como Instalar ZeroClaw: Guia Rápido Amigável para Iniciantes para uma Alternativa Leve do OpenClaw

Por que ZeroClaw vale a pena instalar

Se você já instalou uma ferramenta de IA, viu o binário chegar no seu “PATH”, e ainda assim não tinha prova de que conseguia alcançar um modelo, entender seu espaço de trabalho ou responder com segurança, você já entende o problema que este guia está resolvendo. Uma instalação concluída apenas prova que arquivos foram copiados. Não prova que o runtime do agente é utilizável.

É aí que ZeroClaw fica interessante. É um runtime de agente de IA leve construído em torno de um único binário Rust, com suporte para provedores de modelo hospedados em vez de uma pilha local pesada no primeiro dia. Na prática, isso significa que é mais próximo de “um runtime controlado de uso de ferramentas” do que “um chatbot em um terminal.” Para leitores curiosos sobre o ângulo “alternativa OpenClaw”, o apelo prático não é hype ou benchmarks. É a história de instalação mais leve, peso de dependência menor, e o fato de testar isso em um VPS Ubuntu parecer gerenciável em vez de se transformar em um projeto de infraestrutura completo.

Este artigo permanece focado em um resultado: instalar ZeroClaw, executar “zeroclaw onboard”, verificar uma primeira sessão CLI segura, e sair com uma ideia realista do que tentar a seguir. Esse é o marco certo para um passo a passo amigável para iniciantes em VPS, porque “funcionando” deve significar uma primeira resposta fundamentada que você possa verificar, não um longo tour de recursos.

📝 Nota: Este guia prova o primeiro uso CLI funcionando. Não é um guia de implantação em produção, e não tenta cobrir Docker, gateways públicos ou serviços em segundo plano

O que ZeroClaw é — em português simples

ZeroClaw é melhor entendido como um runtime de agente do que como “um chatbot de IA.” O modelo é apenas uma parte do sistema. ZeroClaw é a camada que conecta uma conta de provedor, uma escolha de modelo, um perfil de agente e um espaço de trabalho limitado para que a ferramenta possa fazer mais do que responder um prompt isolado.

Os quatro termos abaixo são os que mais importam neste tutorial:

Essa ideia de espaço de trabalho importa mais do que parece. Neste artigo, o espaço de trabalho é a sala que o agente tem permissão para trabalhar. É por isso que instalar ZeroClaw não é o mesmo que configurar ZeroClaw: o binário pode existir no disco enquanto o provedor, modelo, alias e espaço de trabalho ainda estão faltando ou mal configurados.

📝 Nota: Uma instalação bem-sucedida é apenas metade da história. O marco significativo é uma configuração funcionando sob ~/.zeroclaw que possa alcançar um provedor e operar dentro de um espaço de trabalho visível.

Esta é também a forma mais clara de explicar por que algumas pessoas veem ZeroClaw como uma alternativa OpenClaw sem forçar uma comparação completa. O valor não é “OpenClaw reescrito em Rust,” e este guia não o trata dessa forma. O valor é uma postura de auto-hospedagem mais leve, flexibilidade de provedor e um runtime de binário único que é fácil de tentar em um VPS.

Bons primeiros casos de uso são igualmente fundamentados: resumir uma cópia segura de repo, explicar um arquivo de configuração, lidar com uma tarefa auxiliar somente leitura dentro de um espaço de trabalho de baixo risco, ou usá-lo como um assistente limitado para operadores que querem visibilidade antes de permitir qualquer mudança real.

Antes de instalar: linha de base Ubuntu, pré-requisitos e segurança

Antes de executar o instalador, gaste um minuto confirmando que o VPS é realmente um bom ajuste para o caminho que este artigo usa. Os requisitos mínimos são diretos: acesso SSH a um VPS Ubuntu, curl, uma conta de provedor hospedado com uma chave API, e uma máquina ou espaço de trabalho de baixo risco para a primeira sessão.

Execute as verificações abaixo primeiro. Na execução de validação mostrada nas capturas de tela, elas retornaram Ubuntu 24.04.4 LTS (Noble Numbat), x86_64, e /usr/bin/curl. Isso é suficiente para confirmar a linha de base do guia sem fingir que cada servidor retornará saída idêntica.

cat /etc/os-release

uname -m
command -v curl

Para o exemplo de provedor hospedado, OpenRouter é o padrão mais limpo porque mantém o VPS do passo a passo amigável e evita configuração de modelo local no servidor. Se você já usa outro provedor suportado, tudo bem, mas tenha a chave API pronta antes que zeroclaw onboard comece a fazer perguntas. O objetivo aqui é primeiro sucesso, não compra de provedor, então um caminho hospedado limpo é melhor do que tentar avaliar cada provedor na mesma sessão.

ZeroClaw suporta caminhos de instalação pré-construída e de origem. Pense no caminho pré-construído como um aparelho pronto para usar e no caminho de origem como um kit de construção própria. Ambos são legítimos, mas servem leitores diferentes. Para este início rápido, o importante é entender a diferença agora e fazer a recomendação real na etapa de instalação.

⚠️ Aviso: Use esta lista de verificação de primeira execução antes de prosseguir:

• fique em um espaço de trabalho de baixo risco
• mantenha o comportamento supervisionado padrão
• evite exposição pública e dados de produção
• faça a primeira tarefa somente leitura de propósito

Instale ZeroClaw com o script oficial

Com a verificação prévia fora do caminho, use o instalador oficial como o caminho principal. Esta é a rota suportada mais curta para um início rápido de VPS Ubuntu:

curl -fsSL https://raw.githubusercontent.com/zeroclaw-labs/zeroclaw/master/install.sh | bash

Neste caminho de instalação, o script é executado de forma não interativa e leva o caminho de versão pré-construída automaticamente. Na execução de validação para este guia, detectou o alvo Linux, baixou o tarball de versão do GitHub correspondente, verificou o checksum, instalou os ativos do painel web sob ~/.local/share/zeroclaw/web/dist, e colocou o binário zeroclaw em ~/.cargo/bin. Como as capturas de tela foram capturadas da conta raiz, os caminhos concretos mostrados são /root/.local/share/zeroclaw/web/dist, /root/.cargo/bin/zeroclaw, e /root/.bashrc; em uma conta de usuário regular, espere o mesmo layout sob seu próprio diretório inicial.

Esse caminho rápido não é um atalho ou uma instalação menos oficial. É a rota de início rápido normal para o público para o qual este guia é escrito: baixe a versão correspondente, verifique-a e coloque o binário em ~/.cargo/bin/zeroclaw. Se você intencionalmente quer uma compilação de origem, use o caminho de clonagem de repo abaixo em vez de esperar que este fluxo de instalador pare e ofereça uma escolha de compilação separada.

💡 Dica: No Linux, o problema pós-instalação mais comum é PATH, não a instalação em si. Siga a sugestão do instalador para adicionar export PATH=”$HOME/.cargo/bin:$PATH” ao seu perfil de shell e recarregue-o com source ~/.bashrc (ou reabra o shell). Se você só precisa de uma correção temporária para a sessão atual, use a exportação de uma linha mostrada abaixo.

Depois que o binário está no lugar, o script termina com uma mensagem de confirmação não interativa em vez de lançar a configuração automaticamente. Na execução de validação para este guia, essa mensagem de encerramento apontava para zeroclaw quickstart, mas o binário instalado “v0.7.5” expôs onboard como o subcomando de configuração real em zeroclaw –help. Também aponta que zeroclaw daemon é o caminho para o daemon sempre ativo mais painel web enquanto zeroclaw agent é o caminho de chat CLI único.

Para este artigo, continue com zeroclaw onboard a seguir. Isso mantém o passo a passo alinhado à promessa real do artigo: primeira sessão de agente funcionando no terminal, não emparelhamento de painel ou runtime sempre ativo.

Se você é consciente de segurança e prefere inspecionar o instalador antes de executá-lo, use esta abordagem alternativa:

git clone https://github.com/zeroclaw-labs/zeroclaw.git
cd zeroclaw
./install.sh

Antes de pensar em provedores ou prompts, verifique se o binário é chamável no shell:

zeroclaw --version

Se isso funcionar, a instalação em si foi bem-sucedida. Se o shell disser command not found, aplique a correção PATH temporária abaixo e teste novamente:

export PATH="$HOME/.cargo/bin:$PATH"

Separar esta etapa da configuração importa. Um zeroclaw –version funcionando diz que o problema do instalador foi resolvido antes de você começar a depurar a configuração do provedor.

Execute zeroclaw onboard e verifique o que criou

Este é o ponto onde “instalado” precisa se tornar “configurado”. No caminho de instalação não interativo usado acima, o script explicitamente pula o prompt de configuração. Se a mensagem do instalador mencionar zeroclaw quickstart mas o binário não o reconhecer, confie em zeroclaw –help e inicie o assistente de primeira execução com:

zeroclaw onboard

O assistente abre na tela do espaço de trabalho. Na execução capturada, o caminho padrão do espaço de trabalho era /root/.zeroclaw/workspace. A menos que você tenha uma razão forte para movê-lo, aceite o padrão. Em uma conta não raiz, o mesmo layout viverá sob seu próprio diretório inicial.

Para este passo a passo CLI para iniciantes, deixe os perfis de espaço de trabalho múltiplo desabilitados. Ligá-los cria memória separada, segredos e diretórios de auditoria por engajamento, o que pode ser útil depois, mas adiciona sobrecarga mental extra para um primeiro teste de fumaça.

Na tela do provedor, escolha OpenRouter. A lista é muito maior do que um guia para iniciantes precisa, o que é exatamente por que ajuda a escolher um caminho hospedado limpo e ficar com ele para a primeira execução.

Cole sua chave API OpenRouter quando solicitado. A entrada é oculta, e o prompt explicitamente nota que ZeroClaw armazena o segredo via chaveiro do SO quando possível em vez de pedir que você o codifique em config.toml.

A lista de modelos OpenRouter é longa. Na execução capturada, deepseek/deepseek-v4-pro foi selecionado. Você pode escolher outro modelo OpenRouter atual se preferir, mas o resto deste passo a passo segue essa seleção exata.

Quando o assistente pergunta sobre configurações avançadas, deixe-as desligadas para este guia. Ligá-las é para substituições direcionadas como temperatura, tempo limite, URL base ou protocolo de fio.

Na tela de Canais, selecione Concluído sem adicionar Discord, Telegram, Slack ou qualquer outra superfície externa. Isso mantém a primeira validação apenas CLI. Você pode adicionar canais depois que o caminho do agente local funcionar.

Para memória, escolha SQLite com Busca Vetorial (recomendado). É o padrão mais forte aqui porque mantém tudo local enquanto ainda oferece suporte a busca híbrida e embeddings.

Deixe auto-save definido como Sim para que seus próprios prompts sejam registrados como histórico de conversa. Se você depois quiser controle manual mais rigoroso, pode desligar isso e salvar memória apenas explicitamente.

Deixe o controle de hardware desabilitado. Esta configuração de VPS não precisa de GPIO, placas tethered USB ou sondas de depuração.

Para o provedor de túnel público, mantenha-o em nenhum. Isso corresponde à postura de segurança deste artigo: sem exposição pública durante o primeiro teste de fumaça.

Quando a etapa de Personalidade diz que já está configurada, deixe Reconfigurar? em Não. A personalidade padrão é suficiente para validação de primeira execução.

O que importa aqui não é memorizar cada painel do assistente. O que importa é o caminho que as capturas de tela provam: espaço de trabalho único, provedor OpenRouter, entrada de chave API oculta, uma escolha de modelo concreto, sem substituições avançadas, sem canais extras, memória SQLite local, auto-save ativado, hardware desligado, sem túnel público e sem reescrita de personalidade. Isso é mais do que suficiente para produzir uma configuração CLI utilizável primeiro sob ~/.zeroclaw.

Após o onboarding terminar, confirme que o diretório de configuração principal e o espaço de trabalho existem:

Se a execução de onboarding for concluída com sucesso, você deve voltar ao shell com uma mensagem carregada de config como a abaixo:

ls ~/.zeroclaw
ls ~/.zeroclaw/workspace

Na execução capturada, ~/.zeroclaw continha config.toml e workspace/, e o espaço de trabalho em si mostrou IDENTITY.md e SOUL.md.

Isso já é suficiente para provar que ZeroClaw agora tem uma sala de operação, não apenas um binário instalado. É também por que a analogia do espaço de trabalho é útil: você está verificando que a sala existe, que o agente tem contexto dentro dela, e que a configuração foi além de “o instalador terminou.” Arquivos como IDENTITY.md e SOUL.md não são decorativos. Eles fazem parte do contexto que ZeroClaw usa para entender como deve se comportar dentro daquele espaço de trabalho.

Antes do primeiro prompt ao vivo, execute uma verificação de saúde compacta:

zeroclaw status

zeroclaw doctor

Para este primeiro teste de fumaça apenas CLI, não entre em pânico se zeroclaw doctor não for perfeitamente limpo. Na execução capturada, as verificações importantes passaram: o arquivo de configuração foi encontrado, o provedor openrouter era válido, a chave API foi configurada, o modelo padrão foi definido e o espaço de trabalho existia e era gravável.

Os avisos e erros restantes não são críticos para um chat de terminal: “nenhum canal configurado” é esperado porque o passo a passo intencionalmente pulou Discord, Telegram e outros canais externos; AGENTS.md não encontrado (opcional) é explicitamente não bloqueador; daemon_state.json não encontrado apenas significa que o daemon sempre ativo não está rodando ainda; e a reclamação de listagem de modelo ao vivo do OpenRouter é melhor lida como uma limitação de sonda do que prova de que a configuração do provedor falhou, especialmente porque a saída ainda relata openrouter: 344 modelos.

grep -E 'default_provider|default_model|[agents.|[risk_profiles.' ~/.zeroclaw/config.toml

O sinal de sucesso aqui é operacional, não cosmético. zeroclaw status é a fonte de verdade mais clara para o resumo de runtime ativo, zeroclaw doctor diz se algo importante está quebrado, e a saída grep é melhor tratada como uma espiada aproximada em entradas de configuração relacionadas a provedor/modelo em vez de uma perfeita. Espere que a redação e correspondências exatas variem por versão. Você não está procurando por uma parede perfeita de texto verde. Você está procurando pela ausência de bloqueadores de primeira execução e pela presença de dados de configuração reais.

📝 Nota: config.toml pode não mostrar sua chave API em texto simples. Isso pode ser normal. Na execução de onboarding capturada, o prompt de chave API explicitamente disse que o segredo seria armazenado via chaveiro do SO quando possível, então “nenhuma chave visível no arquivo TOML” não é a mesma coisa que “configuração falhou.”

Inicie o primeiro chat CLI seguro

Com a configuração e espaço de trabalho no lugar, lance o agente em modo interativo:

zeroclaw agent

Na execução capturada, ZeroClaw carregou a configuração, inicializou memória com suporte SQLite, imprimiu o banner de modo interativo e caiu para o prompt >. O objetivo não é iniciar uma demo chamativa. O objetivo é provar conectividade de ponta a ponta, configuração válida e consciência de espaço de trabalho fundamentada em um passo de baixo risco. Um teste somente leitura oferece muito mais sinal útil neste estágio do que um prompt capaz de escrita “veja o que pode fazer”.

Para o primeiro prompt, use esta verificação exata somente leitura:

tell me your current workspace path, list the top-level files you can see there, and briefly explain what each one is for. Do not create, edit, or delete anything.

Como o runtime está em modo supervisionado, a primeira resposta útil pode exigir uma aprovação de ferramenta. Na execução capturada, ZeroClaw pediu para executar um comando shell somente leitura: “pwd && echo “—-” && ls -la”

Esse é exatamente o tipo de comando que você quer para este teste de fumaça: imprime o caminho do espaço de trabalho e lista o conteúdo de nível superior sem mudar nada. Aprove-o com Y para um sim único. Você também pode negá-lo com N, mas então o agente perderia a forma mais fácil de responder a pergunta a partir do estado real do sistema de arquivos em vez de adivinhar.

📝 Nota:Você também pode ver um aviso de rastreamento de custo para o modelo OpenRouter selecionado antes do prompt de aprovação. Na execução capturada, ZeroClaw avisou que nenhuma entrada de preço foi definida para openrouter/deepseek/deepseek-v4-pro. Isso não bloqueia o chat em si. Apenas significa que o uso de token pode ser registrado com custo zero até você definir preço de modelo explicitamente.

Este prompt é forte porque testa três coisas ao mesmo tempo. Primeiro, ZeroClaw tem que alcançar o provedor e obter uma resposta de volta. Segundo, o agente tem que entender o espaço de trabalho configurado. Terceiro, a resposta tem que ser específica o suficiente para que você possa compará-la contra o que está realmente no disco. Em outras palavras, isso prova que o agente está ficando dentro da sala que lhe foi dada.

Uma boa primeira resposta deve atender a quatro condições:

• sem erros de autenticação ou provedor
• sem “config não encontrado” ou falhas de modelo faltante
• o caminho correto do espaço de trabalho aparece na resposta
• arquivos reais de nível superior são nomeados, sem afirmação de que algo foi alterado

Se você quer uma forma diferente de invocar o agente, você pode enviar o mesmo prompt como um comando único em vez de ficar na sessão interativa. Trate isso como opcional, não o passo a passo principal. O caminho interativo ainda é a melhor primeira experiência porque torna o runtime parecer observável em vez de mágico.

zeroclaw agent -m "tell me your current workspace path, list the top-level files you can see there, and briefly explain what each one is for. Do not create, edit, or delete anything."

O que fazer a seguir uma vez que ZeroClaw funciona

O movimento certo a seguir não é ligar cada recurso que você pode encontrar. É adicionar uma camada controlada por vez, para que você sempre saiba qual mudança introduziu novo risco ou novo atrito.

💡 Dica: Uma vez que o primeiro chat seguro funciona, mantenha a mesma disciplina para a próxima fase. Mude para uma cópia segura de repo ou diretório de notas primeiro, mantenha as tarefas somente leitura onde possível, e expanda privilégios apenas depois que o fluxo de trabalho base parecer previsível.

Boas tarefas de acompanhamento são propositalmente chatas: resumir um README, explicar um arquivo de configuração ou listar ideias de limpeza sem mudar nada. Esse tipo de trabalho é sinal alto porque usa o mesmo runtime que você acabou de validar, mas não força você para acesso de escrita antes de confiar na ferramenta. Se você quer um melhor primeiro espaço de trabalho real, use uma cópia segura de repo, um diretório de notas de preparação ou uma pequena pasta de docs interna em vez de qualquer coisa voltada para produção.

Bons próximos passos, em ordem, parecem assim:

• aponte ZeroClaw para uma cópia segura de repo ou diretório de notas
• tente uma tarefa auxiliar somente leitura
• compare provedores apenas depois que o fluxo de trabalho base parecer estável
• veja serviços, canais ou Docker depois como projetos separados

Se você quer comparar provedores depois, faça isso depois que o fluxo de trabalho base estiver estável. Se você quer o próximo passo de infraestrutura após sucesso CLI, estes são os comandos que vale a pena conhecer:

zeroclaw service install
zeroclaw service start
zeroclaw service status

Esse é o ponto onde este artigo deve parar e o próximo tópico deve começar. Gerenciamento de serviço, implantação Docker, gateways públicos, canais de mensagens e endurecimento de segurança mais profundo merecem seus próprios passo a passos.

Se este primeiro teste de fumaça foi útil, um VPS Ubuntu do AlexHost é um lugar natural para continuar experimentando com um runtime de agente leve sem transformar o primeiro dia em um projeto de plataforma completo. A forma certa de continuar é para fora, não para os lados: use a configuração oficial, serviço, provedor e documentos de segurança quando estiver pronto para a próxima camada.

Conclusão: de curioso a operacional

O resultado importante não é que ZeroClaw instalou. O resultado importante é que respondeu com segurança a partir de uma primeira sessão verificada no VPS. Isso significa que a linha de base Ubuntu verificou, o instalador foi executado, “zeroclaw onboard” foi concluído, a configuração e espaço de trabalho foram criados, as verificações de saúde pareciam sensatas e a primeira resposta somente leitura voltou fundamentada em contexto de espaço de trabalho real.

Esse é um ponto de parada significativo. Mantenha seus primeiros experimentos pequenos, supervisionados e observáveis, depois expanda uma camada por vez em direção a serviços, limites de segurança mais difíceis ou integrações de canal quando você realmente precisar deles. Para um primeiro início rápido de VPS Ubuntu, confiança controlada é a vitória. Você não precisa sair deste artigo com uma pilha de automação completa. Você precisa sair sabendo que o runtime funciona, o limite de segurança está intacto e o próximo passo é sua escolha em vez de um palpite.