O OpenClaw fornece três scripts de instalação, servidos porDocumentation Index
Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt
Use this file to discover all available pages before exploring further.
openclaw.ai.
| Script | Plataforma | O que ele faz |
|---|---|---|
install.sh | macOS / Linux / WSL | Instala o Node se necessário, instala o OpenClaw via npm (padrão) ou git, e pode executar a integração inicial. |
install-cli.sh | macOS / Linux / WSL | Instala Node + OpenClaw em um prefixo local (~/.openclaw) com modos npm ou checkout git. Não requer root. |
install.ps1 | Windows (PowerShell) | Instala o Node se necessário, instala o OpenClaw via npm (padrão) ou git, e pode executar a integração inicial. |
Comandos rápidos
- install.sh
- install-cli.sh
- install.ps1
Se a instalação for bem-sucedida, mas
openclaw não for encontrado em um novo terminal, consulte Solução de problemas do Node.js.install.sh
Fluxo (install.sh)
Detectar SO
Compatível com macOS e Linux (incluindo WSL). Se o macOS for detectado, instala o Homebrew se estiver ausente.
Garantir Node.js 24 por padrão
Verifica a versão do Node e instala o Node 24 se necessário (Homebrew no macOS, scripts de configuração NodeSource no Linux apt/dnf/yum). O OpenClaw ainda oferece suporte ao Node 22 LTS, atualmente
22.16+, para compatibilidade.Instalar OpenClaw
- método
npm(padrão): instalação npm global - método
git: clona/atualiza o repositório, instala dependências com pnpm, compila e então instala o wrapper em~/.local/bin/openclaw
Tarefas pós-instalação
- Atualiza um serviço Gateway carregado na medida do possível (
openclaw gateway install --force, depois reinicia) - Executa
openclaw doctor --non-interactiveem upgrades e instalações git (na medida do possível) - Tenta a integração inicial quando apropriado (TTY disponível, integração inicial não desabilitada e verificações de bootstrap/configuração aprovadas)
- Define
SHARP_IGNORE_GLOBAL_LIBVIPS=1por padrão
Detecção de checkout do código-fonte
Se executado dentro de um checkout do OpenClaw (package.json + pnpm-workspace.yaml), o script oferece:
- usar checkout (
git), ou - usar instalação global (
npm)
npm e um aviso será exibido.
O script sai com o código 2 para seleção de método inválida ou valores de --install-method inválidos.
Exemplos (install.sh)
- Padrão
- Ignorar integração inicial
- Instalação Git
- GitHub main via npm
- Execução de teste
Referência de flags
Referência de flags
| Flag | Descrição |
|---|---|
--install-method npm|git | Escolha o método de instalação (padrão: npm). Alias: --method |
--npm | Atalho para o método npm |
--git | Atalho para o método git. Alias: --github |
--version <version|dist-tag|spec> | versão npm, dist-tag ou especificação de pacote (padrão: latest) |
--beta | Use a dist-tag beta se disponível; caso contrário, faça fallback para latest |
--git-dir <path> | Diretório de checkout (padrão: ~/openclaw). Alias: --dir |
--no-git-update | Ignora git pull para checkout existente |
--no-prompt | Desabilita prompts |
--no-onboard | Ignora a integração inicial |
--onboard | Habilita a integração inicial |
--dry-run | Imprime ações sem aplicar alterações |
--verbose | Habilita saída de depuração (set -x, logs npm em nível notice) |
--help | Mostra o uso (-h) |
Referência de variáveis de ambiente
Referência de variáveis de ambiente
| Variável | Descrição |
|---|---|
OPENCLAW_INSTALL_METHOD=git|npm | Método de instalação |
OPENCLAW_VERSION=latest|next|main|<semver>|<spec> | versão npm, dist-tag ou especificação de pacote |
OPENCLAW_BETA=0|1 | Usa beta se disponível |
OPENCLAW_GIT_DIR=<path> | Diretório de checkout |
OPENCLAW_GIT_UPDATE=0|1 | Alterna atualizações git |
OPENCLAW_NO_PROMPT=1 | Desabilita prompts |
OPENCLAW_NO_ONBOARD=1 | Ignora a integração inicial |
OPENCLAW_DRY_RUN=1 | Modo de execução de teste |
OPENCLAW_VERBOSE=1 | Modo de depuração |
OPENCLAW_NPM_LOGLEVEL=error|warn|notice | Nível de log do npm |
SHARP_IGNORE_GLOBAL_LIBVIPS=0|1 | Controla o comportamento sharp/libvips (padrão: 1) |
install-cli.sh
Projetado para ambientes em que você quer tudo sob um prefixo local
(padrão
~/.openclaw) e sem dependência do Node do sistema. Oferece suporte a instalações npm
por padrão, além de instalações por checkout git no mesmo fluxo de prefixo.Fluxo (install-cli.sh)
Instalar runtime local do Node
Baixa um tarball Node LTS compatível e fixado (a versão é incorporada no script e atualizada de forma independente) para
<prefix>/tools/node-v<version> e verifica SHA-256.Garantir Git
Se o Git estiver ausente, tenta instalar via apt/dnf/yum no Linux ou Homebrew no macOS.
Instalar OpenClaw sob o prefixo
- método
npm(padrão): instala sob o prefixo com npm e então grava o wrapper em<prefix>/bin/openclaw - método
git: clona/atualiza um checkout (padrão~/openclaw) e ainda grava o wrapper em<prefix>/bin/openclaw
Exemplos (install-cli.sh)
- Padrão
- Prefixo personalizado + versão
- Instalação Git
- Saída JSON para automação
- Executar integração inicial
Referência de flags
Referência de flags
| Flag | Descrição |
|---|---|
--prefix <path> | Prefixo de instalação (padrão: ~/.openclaw) |
--install-method npm|git | Escolha o método de instalação (padrão: npm). Alias: --method |
--npm | Atalho para o método npm |
--git, --github | Atalho para o método git |
--git-dir <path> | Diretório de checkout Git (padrão: ~/openclaw). Alias: --dir |
--version <ver> | Versão ou dist-tag do OpenClaw (padrão: latest) |
--node-version <ver> | Versão do Node (padrão: 22.22.0) |
--json | Emite eventos NDJSON |
--onboard | Executa openclaw onboard após a instalação |
--no-onboard | Ignora a integração inicial (padrão) |
--set-npm-prefix | No Linux, força o prefixo npm para ~/.npm-global se o prefixo atual não for gravável |
--help | Mostra o uso (-h) |
Referência de variáveis de ambiente
Referência de variáveis de ambiente
| Variável | Descrição |
|---|---|
OPENCLAW_PREFIX=<path> | Prefixo de instalação |
OPENCLAW_INSTALL_METHOD=git|npm | Método de instalação |
OPENCLAW_VERSION=<ver> | Versão do OpenClaw ou dist-tag |
OPENCLAW_NODE_VERSION=<ver> | Versão do Node |
OPENCLAW_GIT_DIR=<path> | Diretório de checkout do Git para instalações via git |
OPENCLAW_GIT_UPDATE=0|1 | Alternar atualizações do git para checkouts existentes |
OPENCLAW_NO_ONBOARD=1 | Pular integração inicial |
OPENCLAW_NPM_LOGLEVEL=error|warn|notice | Nível de log do npm |
SHARP_IGNORE_GLOBAL_LIBVIPS=0|1 | Controlar o comportamento de sharp/libvips (padrão: 1) |
install.ps1
Fluxo (install.ps1)
Garantir Node.js 24 por padrão
Se estiver ausente, tenta instalar via winget, depois Chocolatey e depois Scoop. Node 22 LTS, atualmente
22.16+, continua compatível.Instalar o OpenClaw
- Método
npm(padrão): instalação global do npm usando a-Tagselecionada, iniciada de um diretório temporário de instalação gravável para que shells abertos em pastas protegidas, comoC:\, ainda funcionem - Método
git: clona/atualiza o repositório, instala/compila com pnpm e instala o wrapper em%USERPROFILE%\.local\bin\openclaw.cmd
Tarefas pós-instalação
- Adiciona o diretório bin necessário ao PATH do usuário quando possível
- Atualiza um serviço de Gateway carregado em modo de melhor esforço (
openclaw gateway install --force, depois reinicia) - Executa
openclaw doctor --non-interactiveem atualizações e instalações via git (melhor esforço)
Exemplos (install.ps1)
- Padrão
- Instalação via Git
- main do GitHub via npm
- Diretório git personalizado
- Simulação
- Rastreamento de depuração
Referência de flags
Referência de flags
| Flag | Descrição |
|---|---|
-InstallMethod npm|git | Método de instalação (padrão: npm) |
-Tag <tag|version|spec> | dist-tag, versão ou especificação de pacote do npm (padrão: latest) |
-GitDir <path> | Diretório de checkout (padrão: %USERPROFILE%\openclaw) |
-NoOnboard | Pular integração inicial |
-NoGitUpdate | Pular git pull |
-DryRun | Apenas imprimir ações |
Referência de variáveis de ambiente
Referência de variáveis de ambiente
| Variável | Descrição |
|---|---|
OPENCLAW_INSTALL_METHOD=git|npm | Método de instalação |
OPENCLAW_GIT_DIR=<path> | Diretório de checkout |
OPENCLAW_NO_ONBOARD=1 | Pular integração inicial |
OPENCLAW_GIT_UPDATE=0 | Desabilitar git pull |
OPENCLAW_DRY_RUN=1 | Modo de simulação |
Se
-InstallMethod git for usado e o Git estiver ausente, o script sai e imprime o link do Git for Windows.CI e automação
Use flags/variáveis de ambiente não interativas para execuções previsíveis.- install.sh (npm não interativo)
- install.sh (git não interativo)
- install-cli.sh (JSON)
- install.ps1 (pular integração inicial)
Solução de problemas
Por que o Git é obrigatório?
Por que o Git é obrigatório?
O Git é obrigatório para o método de instalação
git. Para instalações npm, o Git ainda é verificado/instalado para evitar falhas spawn git ENOENT quando dependências usam URLs git.Por que o npm encontra EACCES no Linux?
Por que o npm encontra EACCES no Linux?
Algumas configurações do Linux apontam o prefixo global do npm para caminhos pertencentes ao root.
install.sh pode trocar o prefixo para ~/.npm-global e anexar exportações de PATH aos arquivos rc do shell (quando esses arquivos existem).Problemas com sharp/libvips
Problemas com sharp/libvips
Os scripts usam
SHARP_IGNORE_GLOBAL_LIBVIPS=1 por padrão para evitar que sharp seja compilado contra a libvips do sistema. Para substituir:Windows: "npm error spawn git / ENOENT"
Windows: "npm error spawn git / ENOENT"
Instale o Git for Windows, reabra o PowerShell e execute novamente o instalador.
Windows: "openclaw is not recognized"
Windows: "openclaw is not recognized"
Execute
npm config get prefix e adicione esse diretório ao PATH do usuário (não é necessário o sufixo \bin no Windows), depois reabra o PowerShell.Windows: como obter saída detalhada do instalador
Windows: como obter saída detalhada do instalador
install.ps1 atualmente não expõe uma opção -Verbose.
Use o rastreamento do PowerShell para diagnósticos no nível do script:openclaw não encontrado após a instalação
openclaw não encontrado após a instalação
Geralmente é um problema de PATH. Consulte solução de problemas do Node.js.