Como Implementar o OpenClaw

1. Visão Geral

Este tutorial orienta-o na implementação do OpenClaw num dispositivo a correr CasaOS/ZimaOS, completando a configuração básica e permitindo a interação com o modelo de IA via Telegram. Usando um bot do Telegram como exemplo, este tutorial cobre todo o processo desde a configuração do fornecedor do modelo até ao emparelhamento do bot.

1.1 Objetivos

  • Completar a configuração inicial do OpenClaw, incluindo:

  • Ligar um fornecedor de modelo de IA personalizado

  • Criar e vincular um bot do Telegram para permitir conversas com IA através de mensagens diretas

  • Visualizar e gerir o estado do OpenClaw através da interface Web

1.2 Ambiente

  • Especificações de Hardware Recomendadas:

    • 4 GB RAM
    • 20 GB de Armazenamento

  • Software: CasaOS v0.4.15 / ZimaOS v1.5.4 (última versão)

  • Rede: O dispositivo deve estar ligado à internet e ser capaz de aceder à API do Telegram. Recomenda-se uma ligação com cabo para maior estabilidade.

1.3 Notas de Utilização

  • Operação Contínua: O OpenClaw foi concebido para funcionar 24/7. Coloque o seu ZimaBlade numa área bem ventilada com temperatura ambiente estável para garantir desempenho confiável a longo prazo e evitar throttling térmico.

  • Expansão de Armazenamento: O armazenamento interno do ZimaBlade é limitado. Se planeia utilizar intensamente funcionalidades de memória ou logging, recomenda-se fortemente ligar um disco externo para armazenar histórico de conversas e dados da aplicação.

1.3 Pré-requisitos

Nota: Na interface de configuração do OpenClaw, use a barra de espaço para selecionar uma opção e Enter para confirmar.

1.4 Passos de Forma Resumida

  • Instalar o OpenClaw na App Store do CasaOS / ZimaOS.

  • Abrir um terminal — conectar via SSH (recomendado) ou usar o terminal local.

  • Mudar para o modo administrador: executar su e introduzir a senha padrão casaos.

  • Entrar no container OpenClaw: docker exec -it openclaw bash

  • Iniciar o assistente de configuração: node /app/dist/index.js config

  • Configurar o fornecedor do modelo: selecionar Model, escolher custom provider, depois introduzir Base URL, API Key e Model ID.

  • Configurar o canal do Telegram: selecionar Channels → Configure/link → Telegram, criar um bot via BotFather, inserir o Token e definir a política DM para Pairing (recomendado).

  • Completar o emparelhamento: enviar /start ao seu bot no Telegram para receber um código de emparelhamento, depois executar openclaw pairing approve telegram <pairing-code> no terminal.

  • Aceder à interface Web em https://<ip>:24190?token=casaos.

2. Passos Detalhados (Exemplo CasaOS)

2.1 Abrir um Terminal

Após instalar o OpenClaw através da interface Web do CasaOS, abra um terminal para iniciar a configuração. Existem duas formas de o fazer:

A. SSH a partir do seu computador (recomendado — mais fácil copiar e colar comandos)

Abra o Terminal.
Execute o seguinte comando:

ssh <username>@<ip>

Por exemplo: ssh [email protected]
Terminal showing the SSH command being entered
Se for a primeira vez a conectar, verá o prompt:

Are you sure you want to continue connecting (yes/no)?

Digite yes e pressione Enter.

B. Input diretamente no ZimaBlade

Ligue um teclado e monitor diretamente ao ZimaBlade e use o terminal local.

2.2 Mudar para o Modo Administrador

Execute o seguinte comando e pressione Enter:

su

Introduza a senha padrão casaos.

A senha não será exibida enquanto digita — isto é normal.
Se estiver a usar ZimaOS, não é necessária senha.

Terminal showing the prompt has switched to the root user

Agora possui os privilégios de administrador necessários para modificar as configurações do sistema.

2.3 Entrar no Assistente de Configuração

Passo 1 — Entrar no container OpenClaw:

docker exec -it openclaw bash

Terminal prompt changed to root@openclaw:/app

Quando o prompt mudar para root@openclaw:/app, entrou com sucesso no container. Todas as configurações subsequentes devem ser feitas a partir deste container. Se sair acidentalmente, execute o comando novamente.

Passo 2 — Iniciar o assistente de configuração:

node /app/dist/index.js config

The configuration wizard's initial screen

Passo 3 — Selecionar a localização do Gateway:

Quando solicitado com Where will the Gateway run?, selecione Local (this machine).
Local (this machine) highlighted in the selection menu

A opção destacada é a atualmente selecionada. Pressione Enter para confirmar.

2.4 Configurar o Modelo

1. Selecionar um Fornecedor

Em Select sections to configure, escolha Model.
Cursor on the Model option

Em Model / auth provider, selecione custom provider.
custom provider highlighted

2. Introduzir os Parâmetros do Modelo

Introduza o Base URL (por exemplo, https://api.openai.com/v1).
Base URL input field

Introduza a sua API Key.
API Key input field

Selecione o API format.
API format selection menu

Selecione o Model ID que deseja usar.
Model ID selection list

2.5 Configurar um Canal (Exemplo Telegram)

1. Abrir Configurações do Canal

Em Select sections to configure, escolha Channels.
Cursor on the Channels option

Selecione Configure / link.
Channels submenu showing "Telegram: needs token" status

Selecione Telegram na lista.
Telegram selected in the channel list

2. Obter um Token de Bot

Abra uma conversa com @BotFather no Telegram e envie /newbot para iniciar a criação do bot.
O BotFather irá pedir:

Bot Name: Nome de exibição do seu bot
Username: Um identificador único que deve terminar em bot

Após a criação, o BotFather retornará um HTTP API Token
BotFather conversation

Guarde este Token — será necessário no próximo passo.

3. Introduzir o Token do Bot

Selecione Enter Telegram bot token.
Token input option in the menu

Cole ou digite o Token recebido do BotFather.
Token input field

4. Definir a Política de Acesso DM

Quando perguntado Configure DM access policies now? (default: pairing), selecione Yes.
Policy configuration prompt

Em Telegram DM policy, selecione Pairing (recommended).
Pairing option highlighted

Retorne a Select sections to configure e escolha Continue (Done) para finalizar a configuração do Telegram.
Continue (Done) option highlighted

5. Completar o Emparelhamento

Abra o chat do seu bot no Telegram e envie /start. Aguarde que o bot responda com um código de emparelhamento.
Telegram conversation showing the bot's pairing code reply

No terminal, execute o seguinte comando, substituindo <your-pairing-code> pelo código recebido:

id
openclaw pairing approve telegram <your-pairing-code>

Uma mensagem de sucesso confirma que o emparelhamento está completo. Agora pode conversar com a IA diretamente através do seu bot no Telegram.

2.6 Aceder à Interface Web

Uma vez concluída a configuração, abra um navegador e aceda a:

https://<ip>:24190?token=casaos

Substitua <ip> pelo endereço IP do seu dispositivo.
Após abrir a interface Web pela primeira vez, poderá ver uma mensagem “pairing required” no painel do Gateway em vez de conectar diretamente.

Isto é esperado nas versões mais recentes do OpenClaw. O dispositivo da interface Web deve primeiro ser aprovado a partir do container.

1. Entrar no container OpenClaw

Execute:

id
docker exec -it openclaw bash

2. Listar dispositivos pendentes

Dentro do container, execute:

id
node /app/dist/index.js devices list

Se existir um dispositivo não emparelhado, o OpenClaw exibirá um request_id.

3. Aprovar o dispositivo

Execute o seguinte comando e substitua pelo ID real exibido acima:

id
node /app/dist/index.js devices approve <request_id>

Após a aprovação, atualize a página da interface Web e reconecte.
O aviso “pairing required” deverá desaparecer e o painel irá conectar normalmente.
Finalmente, desfrute do OpenClaw!