> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Detalhes internos do instalador

OpenClaw inclui três scripts de instalação, servidos a partir de `openclaw.ai`.

| Script                             | Plataforma           | O que ele faz                                                                                               |
| ---------------------------------- | -------------------- | ----------------------------------------------------------------------------------------------------------- |
| [`install.sh`](#installsh)         | macOS / Linux / WSL  | Instala Node se necessário, instala OpenClaw via npm (padrão) ou git, e pode executar o onboarding.         |
| [`install-cli.sh`](#install-clish) | macOS / Linux / WSL  | Instala Node + OpenClaw em um prefixo local (`~/.openclaw`) com modos npm ou checkout git. Não requer root. |
| [`install.ps1`](#installps1)       | Windows (PowerShell) | Instala Node se necessário, instala OpenClaw via npm (padrão) ou git, e pode executar o onboarding.         |

## Comandos rápidos

<Tabs>
  <Tab title="install.sh">
    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash
    ```

    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --help
    ```
  </Tab>

  <Tab title="install-cli.sh">
    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash
    ```

    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --help
    ```
  </Tab>

  <Tab title="install.ps1">
    ```powershell theme={"theme":{"light":"min-light","dark":"min-dark"}}
    iwr -useb https://openclaw.ai/install.ps1 | iex
    ```

    ```powershell theme={"theme":{"light":"min-light","dark":"min-dark"}}
    & ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -Tag beta -NoOnboard -DryRun
    ```
  </Tab>
</Tabs>

<Note>
  Se a instalação for concluída, mas `openclaw` não for encontrado em um novo terminal, consulte [solução de problemas do Node.js](/pt-BR/install/node#troubleshooting).
</Note>

***

<a id="installsh" />

## install.sh

<Tip>
  Recomendado para a maioria das instalações interativas no macOS/Linux/WSL.
</Tip>

### Fluxo (install.sh)

<Steps>
  <Step title="Detectar SO">
    Compatível com macOS e Linux (incluindo WSL).
  </Step>

  <Step title="Garantir Node.js 24 por padrão">
    Verifica a versão do Node e instala Node 24 se necessário (Homebrew no macOS, scripts de configuração do NodeSource no Linux apt/dnf/yum). No macOS, o Homebrew é instalado somente quando o instalador precisa dele para Node ou Git. OpenClaw ainda oferece suporte ao Node 22 LTS, atualmente `22.19+`, para compatibilidade.
    No Alpine/musl Linux, o instalador usa pacotes apk em vez de NodeSource; os repositórios Alpine configurados devem fornecer Node `22.19+` (Alpine 3.21 ou mais recente no momento da escrita).
  </Step>

  <Step title="Garantir Git">
    Instala Git se estiver ausente usando o gerenciador de pacotes detectado, incluindo Homebrew no macOS e apk no Alpine.
  </Step>

  <Step title="Instalar OpenClaw">
    * método `npm` (padrão): instalação global com npm
    * método `git`: clona/atualiza o repositório, instala dependências com pnpm, compila e então instala o wrapper em `~/.local/bin/openclaw`
  </Step>

  <Step title="Tarefas pós-instalação">
    * Atualiza um serviço gateway carregado em modo melhor esforço (`openclaw gateway install --force`, depois reinicia)
    * Executa `openclaw doctor --non-interactive` em upgrades e instalações git (melhor esforço)
    * Tenta onboarding quando apropriado (TTY disponível, onboarding não desativado, e verificações de bootstrap/config passam)
  </Step>
</Steps>

### 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`)

Se nenhum TTY estiver disponível e nenhum método de instalação estiver definido, o padrão será `npm` e um aviso será exibido.

O script sai com código `2` para seleção de método inválida ou valores de `--install-method` inválidos.

### Exemplos (install.sh)

<Tabs>
  <Tab title="Padrão">
    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash
    ```
  </Tab>

  <Tab title="Pular onboarding">
    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --no-onboard
    ```
  </Tab>

  <Tab title="Instalação git">
    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --install-method git
    ```
  </Tab>

  <Tab title="Checkout do main no GitHub">
    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --install-method git --version main
    ```
  </Tab>

  <Tab title="Execução de teste">
    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --dry-run
    ```
  </Tab>
</Tabs>

<AccordionGroup>
  <Accordion title="Referência de flags">
    | Flag                                  | Descrição                                                                 |
    | ------------------------------------- | ------------------------------------------------------------------------- |
    | `--install-method npm\|git`           | Escolhe 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 do pacote (padrão: `latest`)        |
    | `--beta`                              | Usa a dist-tag beta se disponível; caso contrário, fallback para `latest` |
    | `--git-dir <path>`                    | Diretório do checkout (padrão: `~/openclaw`). Alias: `--dir`              |
    | `--no-git-update`                     | Pula `git pull` para checkout existente                                   |
    | `--no-prompt`                         | Desativa prompts                                                          |
    | `--no-onboard`                        | Pula onboarding                                                           |
    | `--onboard`                           | Ativa onboarding                                                          |
    | `--dry-run`                           | Imprime ações sem aplicar alterações                                      |
    | `--verbose`                           | Ativa saída de depuração (`set -x`, logs npm no nível notice)             |
    | `--help`                              | Mostra o uso (`-h`)                                                       |
  </Accordion>

  <Accordion title="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\|<semver>\|<spec>` | Versão npm, dist-tag ou especificação do pacote                         |
    | `OPENCLAW_BETA=0\|1`                              | Usa beta se disponível                                                  |
    | `OPENCLAW_HOME=<path>`                            | Diretório base para estado do OpenClaw e caminhos git/onboarding padrão |
    | `OPENCLAW_GIT_DIR=<path>`                         | Diretório do checkout                                                   |
    | `OPENCLAW_GIT_UPDATE=0\|1`                        | Alterna atualizações git                                                |
    | `OPENCLAW_NO_PROMPT=1`                            | Desativa prompts                                                        |
    | `OPENCLAW_NO_ONBOARD=1`                           | Pula onboarding                                                         |
    | `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                                                     |
  </Accordion>
</AccordionGroup>

***

<a id="install-clish" />

## install-cli.sh

<Info>
  Projetado para ambientes nos quais você quer tudo sob um prefixo local
  (padrão `~/.openclaw`) e nenhuma dependência de 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.
</Info>

### Fluxo (install-cli.sh)

<Steps>
  <Step title="Instalar runtime Node local">
    Baixa um tarball Node LTS compatível fixado (a versão é incorporada no script e atualizada independentemente) para `<prefix>/tools/node-v<version>` e verifica SHA-256.
    No Alpine/musl Linux, onde Node não publica tarballs compatíveis para o runtime fixado, instala `nodejs` e `npm` com `apk` e vincula esse runtime ao caminho do wrapper no prefixo. Os repositórios Alpine devem fornecer Node `22.19+`; use Alpine 3.21 ou mais recente se repositórios mais antigos fornecerem apenas Node 20 ou 21.
  </Step>

  <Step title="Garantir Git">
    Se Git estiver ausente, tenta instalar via apt/dnf/yum/apk no Linux ou Homebrew no macOS.
  </Step>

  <Step title="Instalar OpenClaw sob o prefixo">
    * método `npm` (padrão): instala sob o prefixo com npm, depois 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`
  </Step>

  <Step title="Atualizar serviço gateway carregado">
    Se um serviço gateway já estiver carregado a partir desse mesmo prefixo, o script executa
    `openclaw gateway install --force`, depois `openclaw gateway restart`, e
    testa a integridade do gateway em modo melhor esforço.
  </Step>
</Steps>

### Exemplos (install-cli.sh)

<Tabs>
  <Tab title="Padrão">
    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash
    ```
  </Tab>

  <Tab title="Prefixo personalizado + versão">
    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --prefix /opt/openclaw --version latest
    ```
  </Tab>

  <Tab title="Instalação git">
    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --install-method git --git-dir ~/openclaw
    ```
  </Tab>

  <Tab title="Saída JSON para automação">
    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --json --prefix /opt/openclaw
    ```
  </Tab>

  <Tab title="Executar onboarding">
    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --onboard
    ```
  </Tab>
</Tabs>

<AccordionGroup>
  <Accordion title="Referência de flags">
    | Flag                        | Descrição                                                                              |
    | --------------------------- | -------------------------------------------------------------------------------------- |
    | `--prefix <path>`           | Prefixo de instalação (padrão: `~/.openclaw`)                                          |
    | `--install-method npm\|git` | Escolhe o método de instalação (padrão: `npm`). Apelido: `--method`                    |
    | `--npm`                     | Atalho para o método npm                                                               |
    | `--git`, `--github`         | Atalho para o método git                                                               |
    | `--git-dir <path>`          | Diretório de checkout do Git (padrão: `~/openclaw`). Apelido: `--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`)                                                                    |
  </Accordion>

  <Accordion title="Environment variables reference">
    | 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 ou dist-tag do OpenClaw                                                       |
    | `OPENCLAW_NODE_VERSION=<ver>`               | Versão do Node                                                                       |
    | `OPENCLAW_HOME=<path>`                      | Diretório base para o estado do OpenClaw e caminhos padrão de git/integração inicial |
    | `OPENCLAW_GIT_DIR=<path>`                   | Diretório de checkout do Git para instalações via git                                |
    | `OPENCLAW_GIT_UPDATE=0\|1`                  | Alterna atualizações do git para checkouts existentes                                |
    | `OPENCLAW_NO_ONBOARD=1`                     | Ignora a integração inicial                                                          |
    | `OPENCLAW_NPM_LOGLEVEL=error\|warn\|notice` | Nível de log do npm                                                                  |
  </Accordion>
</AccordionGroup>

***

<a id="installps1" />

## install.ps1

### Fluxo (install.ps1)

<Steps>
  <Step title="Ensure PowerShell + Windows environment">
    Requer PowerShell 5+.
  </Step>

  <Step title="Ensure Node.js 24 by default">
    Se estiver ausente, tenta instalar via winget, depois Chocolatey e depois Scoop. Se nenhum gerenciador de pacotes estiver disponível, o script baixa o zip oficial do Node.js para Windows em `%LOCALAPPDATA%\OpenClaw\deps\portable-node` e o adiciona ao PATH do processo atual e do usuário. O Node 22 LTS, atualmente `22.19+`, continua compatível.
  </Step>

  <Step title="Install OpenClaw">
    * Método `npm` (padrão): instalação global do npm usando o `-Tag` selecionado, iniciada a partir de um diretório temporário gravável do instalador para que shells abertos em pastas protegidas, como `C:\`, ainda funcionem
    * Método `git`: clona/atualiza o repositório, instala/compila com pnpm e instala o wrapper em `%USERPROFILE%\.local\bin\openclaw.cmd`. Se o Git estiver ausente, o script inicializa um MinGit local do usuário em `%LOCALAPPDATA%\OpenClaw\deps\portable-git` e o adiciona ao PATH do processo atual e do usuário.
  </Step>

  <Step title="Post-install tasks">
    * Adiciona o diretório bin necessário ao PATH do usuário quando possível
    * Atualiza um serviço Gateway carregado em modo de melhor esforço (`openclaw gateway install --force`, depois reinicia)
    * Executa `openclaw doctor --non-interactive` em atualizações e instalações via git (melhor esforço)
  </Step>

  <Step title="Handle failures">
    Instalações com `iwr ... | iex` e scriptblock relatam um erro terminativo sem fechar a sessão atual do PowerShell. Instalações diretas com `powershell -File` / `pwsh -File` ainda saem com código diferente de zero para automação.
  </Step>
</Steps>

### Exemplos (install.ps1)

<Tabs>
  <Tab title="Default">
    ```powershell theme={"theme":{"light":"min-light","dark":"min-dark"}}
    iwr -useb https://openclaw.ai/install.ps1 | iex
    ```
  </Tab>

  <Tab title="Git install">
    ```powershell theme={"theme":{"light":"min-light","dark":"min-dark"}}
    & ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -InstallMethod git
    ```
  </Tab>

  <Tab title="GitHub main checkout">
    ```powershell theme={"theme":{"light":"min-light","dark":"min-dark"}}
    & ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -InstallMethod git -Tag main
    ```
  </Tab>

  <Tab title="Custom git directory">
    ```powershell theme={"theme":{"light":"min-light","dark":"min-dark"}}
    & ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -InstallMethod git -GitDir "C:\openclaw"
    ```
  </Tab>

  <Tab title="Dry run">
    ```powershell theme={"theme":{"light":"min-light","dark":"min-dark"}}
    & ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -DryRun
    ```
  </Tab>

  <Tab title="Debug trace">
    ```powershell theme={"theme":{"light":"min-light","dark":"min-dark"}}
    # install.ps1 has no dedicated -Verbose flag yet.
    Set-PSDebug -Trace 1
    & ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard
    Set-PSDebug -Trace 0
    ```
  </Tab>
</Tabs>

<AccordionGroup>
  <Accordion title="Flags reference">
    | 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 npm (padrão: `latest`) |
    | `-GitDir <path>`            | Diretório de checkout (padrão: `%USERPROFILE%\openclaw`)           |
    | `-NoOnboard`                | Ignora a integração inicial                                        |
    | `-NoGitUpdate`              | Ignora `git pull`                                                  |
    | `-DryRun`                   | Imprime apenas as ações                                            |
  </Accordion>

  <Accordion title="Environment variables reference">
    | 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`            | Ignora a integração inicial |
    | `OPENCLAW_GIT_UPDATE=0`            | Desativa git pull           |
    | `OPENCLAW_DRY_RUN=1`               | Modo dry run                |
  </Accordion>
</AccordionGroup>

<Note>
  Se `-InstallMethod git` for usado e o Git estiver ausente, o script tenta inicializar um MinGit local do usuário antes de imprimir o link do Git for Windows.
</Note>

***

## CI e automação

Use flags/variáveis de ambiente não interativas para execuções previsíveis.

<Tabs>
  <Tab title="install.sh (non-interactive npm)">
    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --no-prompt --no-onboard
    ```
  </Tab>

  <Tab title="install.sh (non-interactive git)">
    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    OPENCLAW_INSTALL_METHOD=git OPENCLAW_NO_PROMPT=1 \
      curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash
    ```
  </Tab>

  <Tab title="install-cli.sh (JSON)">
    ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
    curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --json --prefix /opt/openclaw
    ```
  </Tab>

  <Tab title="install.ps1 (skip onboarding)">
    ```powershell theme={"theme":{"light":"min-light","dark":"min-dark"}}
    & ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard
    ```
  </Tab>
</Tabs>

***

## Solução de problemas

<AccordionGroup>
  <Accordion title="Why is Git required?">
    O Git é necessá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.
  </Accordion>

  <Accordion title="Why does npm hit EACCES on 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).
  </Accordion>

  <Accordion title="Windows: &#x22;npm error spawn git / ENOENT&#x22;">
    Execute novamente o instalador para que ele possa inicializar o MinGit local do usuário ou instale o Git for Windows e reabra o PowerShell.
  </Accordion>

  <Accordion title="Windows: &#x22;openclaw is not recognized&#x22;">
    Execute `npm config get prefix` e adicione esse diretório ao PATH do usuário (sem necessidade do sufixo `\bin` no Windows), depois reabra o PowerShell.
  </Accordion>

  <Accordion title="Windows: how to get verbose installer output">
    Atualmente, `install.ps1` não expõe um switch `-Verbose`.
    Use o rastreamento do PowerShell para diagnósticos no nível do script:

    ```powershell theme={"theme":{"light":"min-light","dark":"min-dark"}}
    Set-PSDebug -Trace 1
    & ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard
    Set-PSDebug -Trace 0
    ```
  </Accordion>

  <Accordion title="openclaw not found after install">
    Geralmente é um problema de PATH. Consulte [solução de problemas do Node.js](/pt-BR/install/node#troubleshooting).
  </Accordion>
</AccordionGroup>

## Relacionados

* [Visão geral da instalação](/pt-BR/install)
* [Atualização](/pt-BR/install/updating)
* [Desinstalação](/pt-BR/install/uninstall)