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

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 os arquivos foram copiados. Não prova que o runtime do agente é utilizável.

É aí que ZeroClaw se torna interessante. É um runtime de agente de IA leve construído em torno de um único binário Rust, com suporte para provedores de modelos 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, menor peso de dependências, e o fato de que testá-lo em um VPS Ubuntu parece gerenciável em vez de se transformar em um projeto de infraestrutura completo.

Este artigo mantém foco apertado 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 background

O que é ZeroClaw — em linguagem simples

ZeroClaw é melhor compreendido como um tempo de execução 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 a um único prompt isoladamente.

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

A ideia de espaço de trabalho importa mais do que parece. Neste artigo, o espaço de trabalho é a sala em 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 em ~/.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 tempo de execução de binário único que é fácil de experimentar em um VPS.

Os bons primeiros casos de uso são igualmente fundamentados: resumir uma cópia segura de repositório, 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 desejam 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, dedique um minuto a confirmar que o VPS é realmente uma boa opção para o caminho que este artigo utiliza. Os requisitos mínimos são simples: acesso SSH a um VPS Ubuntu, curl, uma conta de um fornecedor hospedado com uma chave API, e uma máquina ou espaço de trabalho de baixo risco para a primeira sessão.

Execute primeiro as verificações abaixo. Na execução de validação mostrada nas capturas de ecrã, 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á uma saída idêntica.

cat /etc/os-release

uname -m
command -v curl

Para o exemplo de fornecedor hospedado, OpenRouter é a opção padrão mais limpa porque mantém o VPS do passo a passo amigável e evita a configuração de modelo local no servidor. Se já utiliza outro fornecedor suportado, tudo bem, mas tenha a chave API pronta antes de zeroclaw onboard começar a fazer perguntas. O objetivo aqui é o primeiro sucesso, não a avaliação de fornecedores, portanto um caminho hospedado limpo é melhor do que tentar avaliar cada fornecedor na mesma sessão.

ZeroClaw suporta caminhos de instalação pré-construídos 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 é compreender a diferença agora e fazer a recomendação real na etapa de instalação.

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

• mantenha-se num 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 ser apenas leitura propositalmente

Instalar ZeroClaw com o script oficial

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

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 usa automaticamente o caminho de versão pré-construída. Na execução de validação para este guia, detectou o alvo Linux, baixou o tarball de versão correspondente do GitHub, verificou a soma de verificação, instalou os ativos do painel web em ~/.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 normal, espere o mesmo layout no 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 foi escrito: baixe a versão correspondente, verifique-a e coloque o binário em ~/.cargo/bin/zeroclaw. Se você intencionalmente deseja uma compilação a partir do código-fonte, use o caminho de clonagem de repositório abaixo em vez de esperar que este fluxo de instalador pare e ofereça uma opção de compilação separada.

💡 Dica: No Linux, o problema mais comum após a instalação é 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ê apenas precisar 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á em vigor, o script termina com uma mensagem de confirmação não interativa em vez de iniciar 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 funcional no terminal, não emparelhamento de painel ou tempo de execução 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 é importante. Um zeroclaw –version funcional informa 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 foi criado

Este é o ponto onde “instalado” precisa tornar-se “configurado”. No caminho de instalação não-interativo usado acima, o script ignora explicitamente 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 workspace. Na execução capturada, o caminho padrão do workspace era /root/.zeroclaw/workspace. A menos que tenha uma razão forte para movê-lo, aceite o padrão. Em uma conta não-root, o mesmo layout viverá sob seu próprio diretório home.

Para este walkthrough CLI para iniciantes, deixe os perfis multi-workspace desativados. Ativá-los cria diretórios separados de memória, segredos e 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, e é exatamente por isso que ajuda escolher um caminho hospedado limpo e mantê-lo para a primeira execução.

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

A lista de modelos do 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 walkthrough segue essa seleção exata.

Quando o assistente pergunta sobre configurações avançadas, deixe-as desativadas para este guia. Ativá-las é para substituições direcionadas como temperatura, timeout, URL base ou protocolo de transmissão.

Na tela 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 configurado como Sim para que seus próprios prompts sejam registrados como histórico de conversa. Se depois quiser controle manual mais rigoroso, você pode desativar isso e salvar memória apenas explicitamente.

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

Para o provedor de túnel público, mantenha 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 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: workspace único, provedor OpenRouter, entrada de chave API oculta, uma escolha de modelo concreta, sem substituições avançadas, sem canais extras, memória SQLite local, auto-save ativado, hardware desativado, sem túnel público e sem reescrita de personalidade. Isso é mais do que suficiente para produzir uma configuração CLI utilizável sob ~/.zeroclaw.

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

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

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

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

Isso já é suficiente para provar que ZeroClaw agora tem uma sala de operações, não apenas um binário instalado. É também por isso que a analogia do workspace é ú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 desse workspace.

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 estiver perfeitamente limpo. Na execução capturada, as verificações importantes passaram: o arquivo de config foi encontrado, o provedor openrouter era válido, a chave API foi configurada, o modelo padrão foi definido e o workspace 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 walkthrough intencionalmente pulou Discord, Telegram e outros canais externos; AGENTS.md não encontrado (opcional) é explicitamente não-bloqueante; daemon_state.json não encontrado apenas significa que o daemon sempre ativo ainda não está em execução; 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 do runtime ativo, zeroclaw doctor diz se algo importante está quebrado, e a saída grep é melhor tratada como uma espiada aproximada em entradas de config relacionadas a provedor/modelo do que 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 o keyring do SO quando possível, então “nenhuma chave visível no arquivo TOML” não é a mesma coisa que “a configuração falhou.”

Inicie o primeiro chat CLI seguro

Com a config e workspace em vigor, lance o agente em modo interativo:

zeroclaw agent

Na execução capturada, ZeroClaw carregou a config, inicializou memória com suporte SQLite, imprimiu o banner do modo interativo e caiu no prompt >. O objetivo não é iniciar uma demo chamativa. O objetivo é provar conectividade end-to-end, configuração válida e consciência do workspace fundamentada em um passo de baixo risco. Um teste somente leitura lhe dá muito mais sinal útil nesta fase do que um prompt “veja o que pode fazer” com capacidade de escrita.

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

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 aprovação de ferramenta. Na execução capturada, ZeroClaw pediu para executar um comando shell somente leitura: “pwd && echo “—-” && ls -la”

Este é exatamente o tipo de comando que você quer para este teste de fumaça: imprime o caminho do workspace e lista o conteúdo de nível superior sem alterar nada. Aprove com Y para um sim único. Você também poderia negar com N, mas então o agente perderia a forma mais fácil de responder a pergunta a partir do estado real do filesystem 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. Significa apenas que o uso de tokens pode ser registrado com custo zero até que você defina 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 workspace 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, isto prova que o agente está permanecendo dentro da sala que lhe foi dada.

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

• nenhum erro de autenticação ou provedor
• nenhuma falha “config não encontrada” ou modelo ausente
• o caminho correto do workspace 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, pode enviar o mesmo prompt como um comando único em vez de permanecer na sessão interativa. Trate isto como opcional, não o principal do passo a passo. O caminho interativo ainda é a melhor primeira experiência porque torna o runtime 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 quando ZeroClaw funciona

O próximo passo correto não é ativar todos os recursos que conseguir encontrar. É adicionar uma camada controlada de cada vez, para que você sempre saiba qual mudança introduziu novo risco ou novo atrito.

💡 Dica: Depois que o primeiro chat seguro funciona, mantenha a mesma disciplina para a próxima fase. Mude para uma cópia segura do repositório 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 é de alto sinal porque usa o mesmo runtime que você acabou de validar, mas não o força a acessar escrita antes de confiar na ferramenta. Se quiser um primeiro espaço de trabalho real melhor, use uma cópia segura do repositório, um diretório de notas de staging ou uma pequena pasta de documentos internos em vez de qualquer coisa voltada para produção.

Os bons próximos passos, em ordem, parecem assim:

• aponte ZeroClaw para uma cópia segura do repositório 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 mais tarde como projetos separados

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

zeroclaw service install
zeroclaw service start
zeroclaw service status

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

Se este primeiro teste de fumaça foi útil, um VPS Ubuntu da AlexHost é um lugar natural para continuar experimentando com um runtime de agente leve sem transformar o primeiro dia em um projeto de plataforma completa. A maneira correta 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 o ZeroClaw foi instalado. O resultado importante é que ele respondeu com segurança a partir de uma primeira sessão verificada no VPS. Isso significa que a linha de base do Ubuntu foi validada, o instalador foi executado, “zeroclaw onboard” foi concluído, a configuração e o espaço de trabalho foram criados, as verificações de saúde pareciam corretas, e a primeira resposta somente leitura voltou fundamentada no contexto real do espaço de trabalho.

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 rigorosos ou integrações de canais quando você realmente precisar deles. Para um guia de início rápido do Ubuntu VPS, a 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.