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

O OpenClaw é um assistente de IA instalado no seu próprio computador. Pode falar diretamente com ele através do Telegram, Discord, WhatsApp ou Feishu, sem ter de manter outra janela de conversação sempre aberta; as conversas e os registos permanecem nesse computador, onde o assistente também pode executar os passos seguintes.

Preparação antes da instalação

O OpenClaw requer o Node 24.16 ou posterior. Também pode utilizar o Node 26.1 ou posterior, sendo recomendado o Node 26. O Node é o ambiente base necessário para executar o OpenClaw.

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

Se já tiver uma versão mais antiga do Node instalada, não precisa de a desinstalar de imediato. No teste de 2026-10-09, o Node do sistema deste computador era o 24.2.0, abaixo da versão mínima exigida, 24.16, e o script de instalação não interativo preparou automaticamente o Node 24.21.0.

Se quiser uma janela

Aplicação complementar para computador

No Windows, use o instalador do Hub
No macOS, use o DMG do GitHub
Na primeira utilização, pode instalar um Gateway local

Recomendação oficial

Script de instalação

macOS Linux WSL2
No Windows, use o PowerShell
Pode adicionar --no-onboard

Se já tiver Node

Gestor de pacotes

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

Se quiser uma janela, descarregue a aplicação complementar para ambiente de trabalho. Se apenas pretender usar o terminal, execute o script de instalação oficial.

Instalação e primeira execução

Pode instalar a aplicação complementar para ambiente de trabalho, que inclui uma janela, ou fazer a instalação diretamente através do terminal. O Gateway é o serviço local responsável por receber mensagens, chamar o modelo e devolver os resultados. Pode prepará-lo quando abrir a aplicação complementar para ambiente de trabalho pela primeira vez.

Se quiser uma janela

Windows: descarregue e execute OpenClawCompanion-Setup-x64.exe ou OpenClawCompanion-Setup-arm64.exe. O pacote de instalação está assinado e inclui definições, estado no tabuleiro do sistema, conversação e modo node.
macOS: descarregue o .dmg do OpenClaw a partir das releases do GitHub do OpenClaw. Dê preferência ao dmg, embora também possa utilizar o .zip. Após a instalação, abra OpenClaw.app. Se esta versão não incluir ficheiros para macOS, siga as indicações da página da aplicação para macOS.

Na primeira abertura, pode permitir que o OpenClaw prepare o Gateway neste computador ou ligar-se a um Gateway remoto já existente.

Instalar através do terminal

No macOS, Linux e WSL2, utilize:

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

No Windows PowerShell, utilize:

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 a configuração inicial. O assistente de configuração orienta-o durante a primeira configuração.

Se, por enquanto, não quiser iniciar a configuração, utilize o seguinte comando no macOS, Linux e WSL2:

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

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

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

Se já gerir o Node por conta própria, também pode utilizar npm, pnpm ou bun. Com o npm 12 e o npm 11.16 ou posterior, execute:

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

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

Depois de concluir a instalação, execute, por ordem, os três comandos seguintes:

openclaw --version
openclaw doctor
openclaw gateway status

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

Se o terminal indicar que não consegue encontrar openclaw, normalmente isso significa que o diretório bin global do npm não foi adicionado ao PATH. O PATH é a lista de localizações onde o terminal procura programas. Pode comparar os resultados de node -v, npm prefix -g e echo "$PATH", adicionar o diretório bin correspondente ao PATH e voltar a abrir o terminal.

Se já existir uma configuração em utilização em ~/.openclaw, o script de instalação predefinido utilizará esse diretório. Para efetuar uma instalação separada sem alterar 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 predefinido deste script. Em 2026-10-09, este comando instalou o OpenClaw 2026.9.9. Depois da instalação, terá de executar o openclaw existente no diretório bin dessa instalação.

Obter os parâmetros de ligação do OmniProxy

Confirme primeiro que o OmniProxy está em execução. Em seguida, abra a respetiva lista de modelos e prepare os três valores seguintes:

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

O baseUrl é o endereço para o qual o OpenClaw envia os pedidos ao modelo e tem de terminar em /v1. Ao ligar ao OmniProxy, utilize openai-completions no campo api. Altere-o para openai-responses apenas se esse modelo funcionar efetivamente através de /v1/responses.

O Model ID é o identificador completo do modelo na lista. Copie-o exatamente como aparece; se contiver barras, mantenha-as. Os dois nomes seguintes servem apenas como referência na documentação dos fornecedores em 2026-10-09. Não os utilize se não aparecerem na lista: claude-sonnet-5-5 e gpt-6-luna.

Mesmo que o gateway não valide a chave, o campo apiKey tem de conter um valor. Pode utilizar uma sequência de caracteres de preenchimento usada apenas neste computador. Não envie uma chave real para o repositório.

Preencher a configuração da ferramenta

Um Provider pode ser entendido como um conjunto de definições de ligação que o OpenClaw utiliza para encontrar o serviço do modelo. Neste caso, o Provider chama-se omniproxy.

Execute o comando seguinte 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

Este comando grava o Provider e a lista de modelos na configuração. Depois de o comando ser concluído com êxito, não é necessário reiniciar o Gateway.

Em seguida, defina o modelo predefinido. A referência do modelo é composta por omniproxy/ e pelo Model ID. Mantenha todas as barras já existentes no ID. Se o ID apresentado na lista de modelos for mais comprido do que o nome abreviado abaixo, utilize o valor completo da lista:

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

Pode omitir reasoning, input, cost, contextWindow e maxTokens. Quando estes campos não são preenchidos, os modelos de texto são processados da forma predefinida.

Também pode escrever a mesma configuração diretamente no ficheiro de configuração. Na configuração principal, o Provider encontra-se em models.providers. Cada agent também pode ter o seu próprio models.json; um agent é a instância do assistente que recebe efetivamente as tarefas e chama o modelo. O ficheiro encontra-se em agent/models.json, dentro do diretório do agent correspondente em ~/.openclaw/agents/.

Se esse models.json contiver um baseUrl não vazio, o respetivo endereço substitui 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 termina em /v1
Use completions em api
Indique, pelo menos, o id do modelo

Seleção

provider/modelo

Use esta referência em primary
Dê prioridade às variáveis de ambiente para a chave
Use a lista do gateway como referência

Confirme primeiro que o comando pode ser encontrado e, em seguida, introduza o endereço e o modelo. A referência do modelo tem de incluir o nome do Provider.

Verificar com uma tarefa real

Entre num diretório de projeto normal e envie uma mensagem muito 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 esta tarefa do agent é executada localmente, --model especifica o modelo utilizado nesta execução e --timeout 300 define um tempo máximo de espera de 300 segundos.

A resposta do modelo tem de aparecer efetivamente no terminal. Em 2026-10-09, o OpenClaw 2026.9.9 recebeu uma resposta com este comando. A primeira chamada pode demorar um ou dois minutos.

Se aparecer o erro original Request timed out before a response was generated, aumente primeiro o valor de --timeout e envie novamente. Normalmente, isto significa que o tempo de espera não foi suficiente e não que o endereço esteja necessariamente incorreto.

Depois de receber uma resposta curta, peça-lhe que leia um ficheiro local indicado por si. Em seguida, abra o registo de chamadas do OmniProxy e confirme a origem e o Model ID apresentados no registo. A apresentação do número da versão ou de uma saída do doctor não é suficiente para demonstrar que a ligação ao modelo está configurada.

Instalação

O comando responde

É possível apresentar o número da versão
doctor não apresenta bloqueios
O estado do Gateway pode ser consultado

Tarefa

Executou uma pequena tarefa

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

Registo

Visível no gateway

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

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

Erros comuns

Não é possível encontrar openclaw: adicione o diretório bin global do npm ao PATH e volte a abrir o terminal. Se tiver instalado num diretório específico, execute o programa existente no respetivo diretório bin.
node -v apresenta uma versão anterior à 24.16: não precisa de desinstalar primeiro a versão antiga. Verifique o Node preparado pelo script de instalação ou utilize a versão 24.16+, ou 26.1+, conforme indicado na página de instalação. Recomenda-se o Node 26.
O modelo não aparece: o modelo tem de ser incluído no array models de models.providers e, no mínimo, tem de ter o mesmo id. Preencher apenas agents.defaults.models não regista um novo modelo separadamente.
É devolvido o erro 400 e é mencionada a função developer: quando o anfitrião do endereço não for api.openai.com, mantenha a predefinição e não defina supportsDeveloperRole como true. Mesmo que seja definido como true, o valor continuará a ser substituído.
O tempo limite é atingido muito depressa: aumente --timeout para 300 segundos ou mais e não altere já o endereço.
Selecionou gpt-6-luna, mas a chamada de ferramentas falha: este modelo suporta Chat Completions; nas Chat Completions, as chamadas de funções apenas são suportadas quando reasoning_effort está definido como none. Se o ID apresentado na lista for diferente, utilize o ID da lista.
Não é possível ligar ao endereço: confirme que o OmniProxy está em execução, que o baseUrl termina em /v1 e que o endereço gravado na configuração está acessível. Outros endereços de redes privadas têm de ser autorizados separadamente.
Apesar da configuração, continua a ser utilizado outro endereço: verifique se o models.json desse agent contém outro baseUrl.

Referências oficiais

Consulte OpenClaw install para conhecer os passos de instalação. A configuração de um Provider personalizado encontra-se em Custom providers e campos de configuração. Os IDs de modelo utilizados nos exemplos podem ser comparados com a visão geral dos modelos Claude e o GPT-6 Luna.

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

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

Fontes oficiais · OpenClaw ↗