Instalar o OpenClaw CLI para o plugin Nylas

O que este guia cobre

OpenClaw é um framework CLI open-source para criar assistentes de mensagens com IA. Ele se conecta a e-mail, WhatsApp, iMessage e outros canais por meio de um sistema de plugins que atualmente lista mais de 40 pacotes mantidos pela comunidade no npm. Você instala o CLI globalmente via npm, adiciona plugins para as integrações desejadas e configura cada um por meio de um arquivo JSON. O objetivo aqui é instalar o OpenClaw e deixá-lo pronto para executar o plugin Nylas de e-mail, calendário e contatos.

Caminho rápido para usuários Nylas

A maneira mais rápida de executar o Nylas dentro do OpenClaw é uma sequência de 7 passos que leva menos de 3 minutos em uma máquina nova com Node.js já instalado. Os passos cobrem a instalação do CLI, a adição do plugin Nylas, a autorização para sessões de agente e a verificação da conexão com uma consulta de teste nas suas contas de e-mail.

Cada passo abaixo executa um único comando. As chamadas config set gravam no arquivo de configuração JSON do OpenClaw em ~/.openclaw/config.json, e o reinício do gateway aplica essas alterações sem perder sessões ativas.

Se você ainda não tem uma chave de API Nylas, crie uma conta Nylas antes do passo 5 e copie a chave de API para a configuração do plugin OpenClaw.

# 1. Instalar o OpenClaw
npm install -g openclaw

# 2. Verificar se o binário está no PATH
openclaw --version

# 3. Instalar o plugin Nylas
openclaw plugins install @nylas/openclaw-nylas-plugin

# 4. Autorizar o plugin e expor suas ferramentas para sessões de agente
openclaw config set 'plugins.allow' '["nylas"]'
openclaw config set 'tools.alsoAllow' '["nylas"]'

# 5. Configurar sua chave de API Nylas
openclaw config set 'plugins.entries.nylas.config.apiKey' 'YOUR_NYLAS_API_KEY'

# 6. Reiniciar o gateway para recarregar a configuração do plugin
openclaw gateway restart

# 7. Verificar a integração
openclaw plugins list
openclaw run "List my connected email accounts" --plugin nylas

As seções a seguir explicam cada passo de instalação em detalhes, cobrem correções de PATH para ambientes comuns e abordam a solução de problemas tanto no macOS/Linux quanto no Windows.

Qual é o nome do pacote npm do OpenClaw?

O OpenClaw CLI é publicado no npm com o nome de pacote sem escopo openclaw. Não há prefixo de escopo @openclaw/ para o binário principal do CLI. Plugins seguem uma convenção diferente e usam nomes com escopo como @nylas/openclaw-nylas-plugin, mas o próprio CLI é instalado a partir do pacote de nível superior openclaw. O pacote está no npm desde o início de 2025 e tem em média mais de 12.000 downloads semanais em maio de 2026.

Executar npm install -g openclaw coloca o binário openclaw no diretório global de binários do npm, normalmente em $(npm config get prefix)/bin/.

# O nome do pacote npm é "openclaw"
npm install -g openclaw

Instalar o OpenClaw CLI

Instalar o OpenClaw CLI requer Node.js 22.12.0 ou posterior e um único comando npm install -g. A instalação global coloca o binário openclaw no PATH do sistema para que fique disponível em todas as sessões de terminal. Em uma conexão de banda larga típica, a instalação completa leva menos de 60 segundos e baixa aproximadamente 45 MB de dependências.

Verifique sua versão do Node.js primeiro. O OpenClaw usa ES modules nativos e o test runner integrado do Node.js, ambos exigindo Node.js 22.12.0 como mínimo. Versões anteriores falham na inicialização com um erro de sintaxe.

# Verificar a versão do Node.js (deve ser 22.12.0+)
node --version

# Instalar o OpenClaw CLI globalmente
npm install -g openclaw

# Verificar a instalação
openclaw --version

Se você vir um número de versão, a instalação foi bem-sucedida. Um erro "command not found" significa que o diretório global de binários do npm não está no seu PATH — a seção de solução de problemas sobre correções de PATH aborda isso diretamente.

Em sistemas onde você gerencia o Node.js com nvm, certifique-se de que a versão ativa do Node é 22.12.0 ou superior antes de executar a instalação:

# Alternar para o Node.js 22 com nvm
nvm install 22
nvm use 22

# Depois instalar o openclaw
npm install -g openclaw

Quais são os requisitos de sistema?

O OpenClaw roda em macOS (Intel e Apple Silicon), Linux (x64 e arm64) e Windows 10 ou posterior. A única dependência obrigatória é o Node.js 22.12.0+, que ocupa cerca de 80 MB de espaço em disco. O OpenClaw adiciona aproximadamente 45 MB para suas próprias dependências. Nenhuma toolchain de compilação nativa é necessária porque o CLI é JavaScript puro sem add-ons nativos.

Instalar plugins do OpenClaw

Plugins do OpenClaw são pacotes npm que registram novas ferramentas, integrações e comandos no CLI. O gerenciador de plugins integrado cuida do download, resolução de versão e registro de ferramentas. Em maio de 2026, o ecossistema OpenClaw tem mais de 40 plugins publicados cobrindo e-mail, mensagens, CRM e ferramentas para desenvolvedores. Cada plugin é instalado em poucos segundos e ativado após um reinício do gateway.

Os subcomandos openclaw plugins gerenciam o ciclo de vida completo dos plugins: install, list, update e uninstall. Após instalar um plugin ou alterar a configuração de plugins, execute openclaw gateway restart para que o processo do gateway carregue o novo estado do plugin.

# Instalar um plugin
openclaw plugins install <package-name>

# Exemplo: instalar o plugin Nylas para e-mail, calendário e contatos
openclaw plugins install @nylas/openclaw-nylas-plugin

# Verificar se foi instalado
openclaw plugins list

# Reiniciar o gateway para carregar os novos plugins
openclaw gateway restart

Referência de comandos de gerenciamento de plugins

Listar plugins instalados

O comando openclaw plugins list exibe todos os plugins instalados com seu número de versão e status ativo/inativo. A saída é uma tabela de 3 colunas mostrando NAME, VERSION e STATUS. Adicionar a flag --json produz JSON legível por máquina que pode ser encaminhado para jq ou analisado em um script — útil para verificações de CI que validam um conjunto de plugins obrigatórios antes de implantar um agente.

Um plugin aparece como "active" quando suas ferramentas estão carregadas e disponíveis para sessões de agente. O status "inactive" significa que o plugin está instalado mas desabilitado na configuração ou falhou ao inicializar durante o último início do gateway.

# Listar todos os plugins instalados
openclaw plugins list

# Exemplo de saída:
# NAME                              VERSION  STATUS
# @nylas/openclaw-nylas-plugin      1.2.0    active
# openclaw-whatsapp-bridge          0.9.1    active
# openclaw-imsg                     0.8.3    active

# Saída JSON para scripting
openclaw plugins list --json

Desinstalar plugins

O comando openclaw plugins uninstall remove um plugin e cancela o registro de todas as suas ferramentas do CLI em um único passo. A desinstalação tem efeito imediato sem necessidade de reiniciar o gateway, diferente da instalação de plugins que exige um reinício. O pacote npm do plugin é excluído do diretório local ~/.openclaw/plugins/, liberando o espaço em disco que ocupava — normalmente 5-15 MB por plugin dependendo das dependências.

Passe o nome completo do pacote npm exatamente como apareceu durante a instalação. Execute openclaw plugins list depois para confirmar que o plugin não aparece mais.

# Desinstalar um plugin
openclaw plugins uninstall @nylas/openclaw-nylas-plugin

# Verificar se foi removido
openclaw plugins list

OpenClaw no Windows

O OpenClaw roda nativamente no Windows 10 e posterior via PowerShell 5.1+. O caminho de instalação no Windows é o mesmo do macOS e Linux: instale o Node.js 22.12.0 ou posterior e execute npm install -g openclaw. Segundo a Node.js Foundation, o instalador .msi do Windows disponível em nodejs.org adiciona automaticamente o Node.js e o npm ao PATH do sistema, o que significa que o binário do OpenClaw fica disponível sem edições manuais no PATH na maioria dos casos.

# Configuração no Windows PowerShell
# 1. Instale o Node.js 22+ a partir de https://nodejs.org (use o instalador LTS)

# 2. Abra o PowerShell e verifique o Node.js
node --version

# 3. Instale o OpenClaw globalmente
npm install -g openclaw

# 4. Verifique
openclaw --version

# 5. Se receber erros de EACCES ou permissão, execute o PowerShell como Administrador:
# Clique com o botão direito no PowerShell → "Executar como Administrador"
# Depois repita: npm install -g openclaw

No Windows, o diretório de configuração do OpenClaw é %USERPROFILE%\.openclaw\. Plugins e arquivos de configuração ficam nesse diretório. Certifique-se de que seu PATH inclui o diretório global de binários do npm, que o instalador do Node.js normalmente configura automaticamente.

Opcional: configuração de PATH do CLI iMessage

O plugin openclaw-imsg conecta o OpenClaw ao iMessage no macOS. Como o sandboxing de apps do macOS restringe onde binários podem ficar, o plugin não consegue detectar automaticamente o binário do CLI iMessage — você precisa definir o caminho explicitamente via openclaw config set imsg.cliPath. Esse passo extra leva cerca de 30 segundos e é necessário apenas uma vez por máquina.

O binário do CLI iMessage (imsg-cli) é uma ferramenta open-source separada. Se você o instalou via Homebrew, o binário fica em $(brew --prefix)/bin/. Instalações manuais normalmente o colocam em /usr/local/bin/imsg-cli.

# Instalar o plugin iMessage
openclaw plugins install openclaw-imsg

# Definir o caminho do binário do CLI iMessage
openclaw config set imsg.cliPath "/usr/local/bin/imsg-cli"

# Se você instalou o imsg-cli via Homebrew:
openclaw config set imsg.cliPath "$(brew --prefix)/bin/imsg-cli"

# Verificar se o caminho foi definido
openclaw config get imsg.cliPath

# Testar a conexão com o iMessage
openclaw imsg status

O valor de configuração imsg.cliPath deve apontar para o binário real. Se você receber erros "command not found" do plugin, o caminho está errado ou o binário não existe naquele local. Use which imsg-cli para encontrar o caminho correto no seu sistema.

Opcional: integração com WhatsApp

O plugin openclaw-whatsapp-bridge conecta o OpenClaw à API WhatsApp Business, que atende mais de 2 bilhões de usuários ativos mensais segundo o relatório de resultados da Meta de 2025. O plugin gerencia envio, recebimento de mensagens e registro de webhooks através da Cloud API da Meta. Você precisa de uma conta WhatsApp Business e um token de acesso do painel de desenvolvedores da Meta. A configuração leva cerca de 5 minutos quando suas credenciais estão prontas.

Três valores de configuração são obrigatórios: o token de acesso, o ID do número de telefone e o ID da conta business. Todos os três estão disponíveis no Portal de Desenvolvedores da Meta nas configurações do seu app WhatsApp.

# Instalar o plugin de bridge WhatsApp
openclaw plugins install openclaw-whatsapp-bridge

# Configurar suas credenciais do WhatsApp Business
openclaw config set whatsapp.accessToken "YOUR_ACCESS_TOKEN"
openclaw config set whatsapp.phoneNumberId "YOUR_PHONE_NUMBER_ID"
openclaw config set whatsapp.businessAccountId "YOUR_BUSINESS_ACCOUNT_ID"

# Verificar a configuração
openclaw whatsapp status

# Enviar uma mensagem de teste
openclaw whatsapp send --to "+1234567890" --message "Hello from OpenClaw"

O ID do número de telefone identifica qual número WhatsApp envia mensagens em nome do seu agente. Tokens de acesso gerados no Portal de Desenvolvedores da Meta expiram após 24 horas, a menos que você crie um token permanente pela página de Usuários do Sistema nas Configurações Business. Para implantações em produção, use um token permanente para evitar falhas de autenticação.

Opcional: configurar exec-approvals.json

O sistema de aprovação de exec do OpenClaw controla quais comandos shell os plugins podem executar na sua máquina. O arquivo exec-approvals.json define regras baseadas em padrões com 3 ações possíveis: allow, deny ou ask (solicitar confirmação antes de executar). Sem esse arquivo, o OpenClaw solicita confirmação para cada comando shell por padrão, o que significa que plugins não podem executar nada silenciosamente a menos que você aprove explicitamente.

O arquivo de configuração fica em ~/.openclaw/exec-approvals.json no macOS e Linux, ou %USERPROFILE%\.openclaw\exec-approvals.json no Windows. As regras são avaliadas de cima para baixo; o primeiro padrão que corresponder vence. O exemplo abaixo mostra uma configuração típica com 3 regras cobrindo Nylas CLI, curl e exclusão de arquivos.

// Example exec-approvals.json
{
  "version": 1,
  "rules": [
    {
      "pattern": "nylas *",
      "action": "allow",
      "comment": "Allow all Nylas CLI commands"
    },
    {
      "pattern": "curl *",
      "action": "ask",
      "comment": "Prompt before running curl"
    },
    {
      "pattern": "rm *",
      "action": "deny",
      "comment": "Never allow file deletion"
    }
  ],
  "default": "ask"
}

O campo default controla o que acontece quando nenhuma regra corresponde. Defina como "ask" para ser solicitado em comandos desconhecidos, "deny" para bloquear tudo que não for explicitamente permitido, ou "allow" se você confia completamente em todos os plugins. Para a maioria dos usuários, "ask" é o padrão mais seguro.

Você pode inspecionar a configuração atual com cat ou restaurá-la para os padrões do OpenClaw. O comando de reset restaura o exec-approvals.json de fábrica com a ação padrão ask e sem regras personalizadas.

# Visualizar sua configuração atual de exec approvals
cat ~/.openclaw/exec-approvals.json

# Restaurar para os padrões
openclaw config reset exec-approvals

Adicionar o plugin Nylas

O @nylas/openclaw-nylas-plugin adiciona ferramentas nativas de e-mail, calendário e contatos ao OpenClaw. O plugin Nylas suporta 6 provedores de e-mail — Gmail, Outlook, Exchange, Yahoo, iCloud e IMAP — por meio de uma única API. Ele registra mais de 20 ferramentas no OpenClaw cobrindo CRUD de mensagens, gerenciamento de eventos de calendário, busca de contatos e manipulação de anexos.

A instalação requer o nome do pacote npm, uma chave de API Nylas (de dashboard.nylas.com) e um reinício do gateway. A chave de API é armazenada no arquivo de configuração local do OpenClaw e nunca sai da sua máquina.

# Instalar o plugin Nylas
openclaw plugins install @nylas/openclaw-nylas-plugin

# Configurar sua chave de API Nylas
openclaw config set 'plugins.entries.nylas.config.apiKey' 'YOUR_NYLAS_API_KEY'

# Reiniciar o gateway para recarregar a configuração do plugin
openclaw gateway restart

# Verificar se o plugin consegue ver suas contas conectadas
openclaw run "List my connected email accounts" --plugin nylas

Para configuração multi-conta, a tabela completa de referência de ferramentas e solução de problemas por provedor, consulte o guia Instalar o plugin OpenClaw Nylas.

Solução de problemas: "command not found" após npm install -g

Um erro "command not found" após npm install -g openclaw significa que o diretório global de binários do npm não está no PATH do shell. Este é o problema pós-instalação mais comum e afeta aproximadamente 1 em cada 5 usuários no Linux e macOS onde o Node.js foi instalado via nvm ou tarball manual. A correção é encontrar o diretório de prefixo do npm e adicionar seu subdiretório bin/ ao perfil do shell.

Execute npm config get prefix para exibir o diretório. Em uma instalação nvm padrão, o prefixo é normalmente ~/.nvm/versions/node/v22.x.x. O binário openclaw fica em <prefix>/bin/openclaw.

# Descobrir onde o npm instala binários globais
npm config get prefix

# O binário estará em <prefix>/bin/openclaw
# Adicione o diretório bin ao seu PATH

# Para bash (~/.bashrc):
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# Para zsh (~/.zshrc):
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# Verificar se funciona
openclaw --version

Se você usa nvm, o prefixo global muda quando você troca de versão do Node. Certifique-se de instalar o OpenClaw na versão do Node que você usa no dia a dia. Executar nvm use 22 && npm install -g openclaw garante que o binário esteja disponível sempre que o Node 22 estiver ativo.

Solução de problemas: falha na instalação de plugins

Falhas na instalação de plugins via openclaw plugins install se dividem em 3 categorias: incompatibilidade de versão do npm, erros de rede/proxy e erros de permissão de arquivos. A causa mais comum é executar npm 9 ou anterior, que não possui os recursos de resolução de dependências que os plugins do OpenClaw necessitam. O npm 10+ vem por padrão com o Node.js 22. Os passos abaixo abordam cada modo de falha em ordem de probabilidade.

Comece verificando suas versões do Node.js e npm. Se ambas estiverem atualizadas, limpe o cache do npm e tente novamente. Problemas de proxy corporativo e propriedade de arquivos são menos comuns, mas representam cerca de 15% das falhas de instalação reportadas no rastreador de issues do OpenClaw no GitHub.

# 1. Verificar suas versões do Node.js e npm
node --version   # Deve ser 22.12.0+
npm --version    # Deve ser 10+

# 2. Limpar o cache do npm
npm cache clean --force

# 3. Tentar instalar novamente
openclaw plugins install @nylas/openclaw-nylas-plugin

# 4. Se estiver atrás de um proxy corporativo, configure o npm
npm config set proxy http://proxy.company.com:8080
npm config set https-proxy http://proxy.company.com:8080

# 5. Se houver falha de permissão no macOS/Linux, corrija a propriedade do prefixo npm
sudo chown -R $(whoami) $(npm config get prefix)/{lib/node_modules,bin,share}

Solução de problemas: plugin instalado mas não carregando

Quando openclaw plugins list mostra um plugin como "active" mas suas ferramentas ou comandos não estão disponíveis durante sessões de agente, o plugin provavelmente falhou ao inicializar na inicialização. Isso pode acontecer quando os valores de configuração obrigatórios do plugin estão ausentes ou quando um conflito de dependência impede o carregamento do ponto de entrada do plugin. A flag --debug grava logs detalhados de inicialização em stderr, incluindo a mensagem de erro exata do plugin que falhou.

Reinstalar o plugin força um novo download e re-registra as ferramentas do plugin no OpenClaw. O ciclo de desinstalação + instalação leva menos de 10 segundos na maioria das conexões.

# Verificar logs de debug para erros de plugin
openclaw --debug 2>&1 | grep -i plugin

# Reinstalar o plugin problemático
openclaw plugins uninstall <package-name>
openclaw plugins install <package-name>

# Verificar se carregou corretamente
openclaw plugins list

Próximos passos

Com o OpenClaw instalado e o plugin Nylas registrado, o CLI está pronto para automação de e-mail, calendário e contatos. Os guias listados aqui cobrem a configuração de plugins em profundidade, padrões de construção de agentes e resolução de erros para os problemas mais comuns do OpenClaw.

• Instalar o plugin OpenClaw Nylas — adicione ferramentas de e-mail, calendário e contatos com schemas tipados e auto-discovery
• Construir um assistente pessoal com Nylas CLI e OpenClaw — a abordagem baseada em exec usando comandos shell diretamente
• Proteger o acesso a e-mail do OpenClaw — configure allowlists de plugins, credenciais, políticas e aprovações de envio
• CLI de agente de IA para e-mail e calendário — construa ferramentas de e-mail e calendário baseadas em subprocessos para agentes personalizados
• Corrigir erros do OpenClaw CLI — solucione problemas de PATH, permissões npm, versão do Node.js e configuração no Windows
• Referência de comandos do Nylas CLI — referência completa de todos os comandos, flags e opções