Instalação do OpenClaw e configuração do OmniProxy

O OpenClaw é um assistente de IA instalado no seu próprio computador. Você pode conversar com ele diretamente pelo Telegram, Discord, WhatsApp ou Feishu, sem precisar manter outra janela de chat aberta o tempo todo. As conversas e os registros permanecem nesse computador, e ele também pode continuar executando localmente as etapas seguintes.

Preparação antes da instalação

O OpenClaw requer o Node 24.16 ou posterior. Também é possível usar o Node 26.1 ou posterior, sendo recomendado o Node 26. O Node é o ambiente básico de execução necessário para o OpenClaw.

A instalação está disponível para macOS, Linux e Windows. Se o computador não tiver uma versão adequada do Node, o script de instalação preparará o ambiente automaticamente: Node 26 no macOS e Node 24 LTS no Linux. O pnpm só é necessário ao compilar o OpenClaw a partir do código-fonte.

Se já houver uma versão mais antiga do Node no computador, não é necessário desinstalá-la imediatamente. No teste realizado em 2026-10-09, o Node do sistema era a versão 24.2.0, abaixo do requisito de 24.16, e o script de instalação não interativo preparou automaticamente o Node 24.21.0.

Se você quer uma interface

Aplicativo complementar para desktop

No Windows, use o instalador do Hub
No macOS, use o DMG do GitHub
Na primeira execução, é possível instalar um Gateway local

Recomendação oficial

Script de instalação

macOS, Linux e WSL2
No Windows, use PowerShell
É possível adicionar --no-onboard

Node já instalado

Gerenciador de pacotes

npm, pnpm ou bun
Depois, execute onboard
Consulte a versão do Node na página de instalação

Baixe o aplicativo complementar para desktop se quiser uma interface gráfica. Se for usar somente o terminal, execute o script oficial de instalação.

Instalação e primeira inicialização

Você pode instalar o aplicativo complementar para desktop, que tem interface gráfica, ou fazer a instalação diretamente pelo terminal. O Gateway é o serviço local responsável por receber mensagens, chamar o modelo e devolver os resultados. Ele pode ser configurado durante a primeira abertura do aplicativo complementar para desktop.

Se você quiser uma interface gráfica

Windows: baixe e execute OpenClawCompanion-Setup-x64.exe ou OpenClawCompanion-Setup-arm64.exe. O instalador é assinado e inclui configurações, status na bandeja do sistema, chat e modo node.
macOS: baixe o arquivo .dmg do OpenClaw nas releases do GitHub do OpenClaw. Dê preferência ao dmg, embora também seja possível usar o arquivo .zip. Após a instalação, abra o OpenClaw.app. Se essa versão não tiver arquivos para macOS, siga as orientações da página do aplicativo para macOS.

Na primeira abertura, você pode permitir que o OpenClaw prepare o Gateway nesse computador ou se conectar a um Gateway remoto já existente.

Instalação pelo terminal

No macOS, Linux e WSL2, use:

curl -fsSL https://openclaw.ai/install.sh | bash

No Windows PowerShell, use:

iwr -useb https://openclaw.ai/install.ps1 | iex

O script identifica o sistema atual, instala o Node quando necessário, instala o OpenClaw e inicia o assistente de configuração inicial. Esse assistente orientará você durante a primeira configuração.

Se não quiser iniciar o assistente de configuração agora, use o seguinte comando no macOS, Linux ou WSL2:

curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard

No Windows, use a opção oficial -NoOnboard:

& ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard

Se você já gerencia o Node por conta própria, também pode usar npm, pnpm ou bun. Com o npm 12 ou o npm 11.16 e versões posteriores, execute:

npm install -g openclaw@latest --allow-scripts=openclaw
openclaw onboard --install-daemon

No npm 11.15 e em versões anteriores, remova --allow-scripts=openclaw. Ao usar o pnpm, adicione --allow-build=openclaw. Consulte a página de instalação para verificar as diferenças específicas.

Após concluir a instalação, execute estes três comandos na ordem indicada:

openclaw --version
openclaw doctor
openclaw gateway status

openclaw --version mostra a versão, openclaw doctor verifica problemas comuns do ambiente e openclaw gateway status informa se o Gateway está em execução. A instalação básica só estará concluída quando os três comandos apresentarem uma saída normal.

Se o terminal informar que não encontrou openclaw, normalmente o diretório bin global do npm não foi adicionado ao PATH. O PATH é a lista de locais em que o terminal procura programas. Compare os resultados de node -v, npm prefix -g e echo "$PATH", adicione o diretório bin correspondente ao PATH e reabra o terminal.

Se já houver uma configuração em uso em ~/.openclaw, o script de instalação padrão utilizará esse diretório. Para fazer outra instalação sem modificar a configuração original, execute o script não interativo e especifique um novo diretório:

curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install-cli.sh | bash -s -- --prefix "$HOME/openclaw-omniproxy" --no-onboard

--no-onboard é o comportamento padrão desse script. Em 2026-10-09, esse comando foi usado para instalar o OpenClaw 2026.9.9. Após a instalação, execute o openclaw que está no diretório bin desse local.

Obtenção dos parâmetros de conexão no OmniProxy

Primeiro, confirme que o OmniProxy está em execução. Depois, abra a lista de modelos e prepare estes três itens:

baseUrl: https://your-omniproxy-origin.example/v1
apiKey:  <YOUR_OMNIPROXY_API_KEY>
Model ID: copie o ID completo da lista atual de modelos do OmniProxy

baseUrl é o endereço para o qual o OpenClaw envia as solicitações ao modelo e deve terminar em /v1. Na integração com o OmniProxy, use openai-completions em api. Altere para openai-responses somente se esse modelo realmente funcionar por meio de /v1/responses.

Model ID é o identificador completo do modelo na lista. Copie-o exatamente como aparece. Se houver barras no ID, elas também deverão ser mantidas. Os dois nomes a seguir servem apenas como referência com base na documentação dos fornecedores em 2026-10-09. Não os use se eles não estiverem na lista: claude-sonnet-5-5, gpt-6-luna.

Mesmo que o gateway não valide a chave, apiKey ainda deve conter algum valor. Você pode usar uma sequência de caracteres de espaço reservado utilizada apenas nesse computador. Não envie uma chave real para o repositório.

Preenchimento da configuração da ferramenta

Um Provider pode ser entendido como um conjunto de configurações de conexão que o OpenClaw usa para localizar o serviço de modelos. Neste exemplo, o Provider receberá o nome omniproxy.

Execute o comando abaixo no terminal e substitua o endereço, a chave e os dois IDs de modelo pelos seus próprios valores:

openclaw config set models.providers.omniproxy '{"baseUrl":"https://your-omniproxy-origin.example/v1","apiKey":"<YOUR_OMNIPROXY_API_KEY>","api":"openai-completions","models":[{"id":"claude-sonnet-5-5","name":"Claude Sonnet 5.5"},{"id":"gpt-6-luna","name":"GPT-6 Luna"}]}' --strict-json --merge

Esse comando grava o Provider e a lista de modelos na configuração. Depois que o comando for concluído com sucesso, não será necessário reiniciar o Gateway.

Em seguida, defina o modelo padrão. A referência do modelo é composta por omniproxy/ e pelo ID do modelo. Mantenha todas as barras que já existirem no ID. Se o ID na lista de modelos for mais longo do que o nome abreviado abaixo, use o valor completo exibido na lista:

openclaw config set agents.defaults.model.primary '"omniproxy/claude-sonnet-5-5"' --strict-json

reasoning, input, cost, contextWindow e maxTokens podem ser omitidos. Quando esses campos não são preenchidos, os modelos de texto são processados da maneira padrão.

O mesmo conjunto de configurações também pode ser gravado diretamente no arquivo de configuração. Na configuração principal, o Provider fica em models.providers. Cada agent também pode ter seu próprio models.json; um agent é a instância do assistente que realmente recebe tarefas e chama o modelo. O arquivo fica em agent/models.json, dentro do diretório do agent correspondente em ~/.openclaw/agents/.

Se esse models.json tiver um baseUrl não vazio, ele substituirá o endereço da configuração principal.

Verificar a instalação

Três comandos

openclaw --version
openclaw doctor
gateway status

Configuração

models.providers

baseUrl deve terminar em /v1
Use completions em api
O modelo deve incluir pelo menos id

Seleção

provider/modelo

Use esta referência em primary
Prefira usar uma variável de ambiente para a chave
Use a lista do gateway como referência

Primeiro, confirme que o comando pode ser encontrado. Depois, grave o endereço e o modelo. A referência do modelo deve incluir o nome do Provider.

Verificação com uma tarefa real

Entre em um diretório de projeto comum e envie uma mensagem bem curta. Substitua a referência do modelo no comando pelo seu Model ID completo:

openclaw agent --local --model omniproxy/claude-sonnet-5-5 --timeout 300 --message "Responda com uma palavra."

--local indica que essa tarefa do agent será executada localmente, --model define o modelo utilizado nessa execução e --timeout 300 estabelece um tempo máximo de espera de 300 segundos.

Uma resposta real do modelo deve aparecer no terminal. Em 2026-10-09, o OpenClaw 2026.9.9 recebeu uma resposta ao usar esse comando. A primeira chamada pode levar um ou dois minutos.

Se aparecer o erro original Request timed out before a response was generated, primeiro aumente o valor de --timeout e envie a solicitação novamente. Isso normalmente significa que o tempo de espera foi insuficiente, não necessariamente que o endereço está incorreto.

Depois que a resposta curta funcionar, peça ao modelo para ler um arquivo local especificado por você. Em seguida, abra os registros de chamadas do OmniProxy e confirme a origem e o ID do modelo registrados. Apenas obter uma saída do número da versão ou do doctor não comprova que a conexão com o modelo foi configurada completamente.

Instalação

O comando responde

O número da versão é exibido
doctor não encontrou bloqueios
O status do Gateway pode ser consultado

Tarefa

Ele realizou uma pequena tarefa

Por exemplo, ler um arquivo local
A resposta não é um erro
A referência do modelo está correta

Registros

Visível no gateway

A origem é OpenClaw
O ID do modelo corresponde
A chave não foi colocada no repositório

Depois que o comando de versão apresentar uma saída, ainda será necessário receber uma resposta real.

Erros comuns

openclaw não foi encontrado: adicione o diretório bin global do npm ao PATH e reabra o terminal. Se a instalação foi feita em um diretório especificado, execute o programa que está no diretório bin desse local.
node -v está abaixo da versão 24.16: não é necessário desinstalar primeiro a versão antiga. Verifique o Node preparado pelo script de instalação ou use a versão 24.16+, ou 26.1+, conforme a página de instalação. O Node 26 é recomendado.
O modelo não aparece: o modelo deve estar no array models de models.providers e deve ter pelo menos o mesmo id. Configurar apenas agents.defaults.models não registra um novo modelo separadamente.
O serviço retorna o código 400 e menciona a função developer: se o host do endereço não for api.openai.com, mantenha o valor padrão e não defina supportsDeveloperRole como true. Mesmo que seja definido como true, o valor será substituído.
O tempo limite é atingido muito rapidamente: aumente --timeout para 300 segundos ou mais e não altere o endereço primeiro.
As chamadas de ferramentas falham depois de selecionar gpt-6-luna: ele é compatível com Chat Completions. Em Chat Completions, as chamadas de função só são compatíveis quando reasoning_effort está definido como none. Se o ID da lista for diferente, use o valor exibido na lista.
Não é possível acessar o endereço: confirme que o OmniProxy está em execução, que baseUrl termina em /v1 e que o endereço gravado na configuração está acessível. Outros endereços de rede privada precisam ser liberados separadamente.
Mesmo após a configuração, as solicitações continuam indo para outro endereço: verifique se o models.json desse agent contém outro baseUrl.

Referências oficiais

Consulte OpenClaw install para ver as etapas de instalação. Para saber como configurar um Provider personalizado, consulte Custom providers e campos de configuração. Os IDs de modelo usados nos exemplos podem ser comparados com a visão geral dos modelos Claude e com o GPT-6 Luna.

Substitua todos os espaços reservados por valores de sua própria configuração do OmniProxy. Nunca publique uma chave real.

Um resultado salvo ou HTTP 200 sozinho não prova compatibilidade total com o Agente. Verifique a origem e o modelo no registro de chamadas do OmniProxy.

Fontes oficiais · OpenClaw ↗