Setup

Nota: Se é sua primeira vez configurando, comece por Primeiros Passos. Para detalhes do assistente, veja Assistente de Onboarding.

Última atualização: 01/01/2026

TL;DR

  • Personalização fica fora do repositório: ~/.openclaw/workspace (workspace) + ~/.openclaw/openclaw.json (config).
  • Workflow estável: instale o app macOS; deixe ele rodar o Gateway integrado.
  • Workflow bleeding edge: rode o Gateway manualmente via pnpm gateway:watch, depois conecte o app macOS em modo Local.

Pré-requisitos (a partir do código-fonte)

  • Node >=22
  • pnpm
  • Docker (opcional; apenas para setup containerizado/e2e — veja Docker)

Estratégia de personalização (para que atualizações não quebrem nada)

Se você quer “100% personalizado” e atualizações fáceis, mantenha suas customizações em:

  • Config: ~/.openclaw/openclaw.json (JSON/JSON5-ish)
  • Workspace: ~/.openclaw/workspace (skills, prompts, memórias; transforme num repositório git privado)

Bootstrap inicial:

openclaw setup

De dentro deste repositório, use a entrada CLI local:

openclaw setup

Se você ainda não tem uma instalação global, rode via pnpm openclaw setup.

Rodar o Gateway a partir deste repositório

Depois de pnpm build, você pode rodar a CLI empacotada diretamente:

node openclaw.mjs gateway --port 18789 --verbose

Workflow estável (app macOS primeiro)

  1. Instale e abra o OpenClaw.app (menu bar).
  2. Complete o checklist de onboarding/permissões (prompts TCC).
  3. Garanta que o Gateway está em modo Local e rodando (o app gerencia isso).
  4. Conecte as superfícies (exemplo: WhatsApp):
openclaw channels login
  1. Verificação:
openclaw health

Se o onboarding não estiver disponível no seu build:

  • Rode openclaw setup, depois openclaw channels login, e inicie o Gateway manualmente (openclaw gateway).

Workflow bleeding edge (Gateway no terminal)

Objetivo: trabalhar no Gateway TypeScript, ter hot reload e manter a UI do app macOS conectada.

0) (Opcional) Rode o app macOS a partir do código-fonte também

Se você também quer o app macOS no bleeding edge:

./scripts/restart-mac.sh

1) Inicie o Gateway de desenvolvimento

pnpm install
pnpm gateway:watch

gateway:watch roda o gateway em modo watch e recarrega quando há mudanças no TypeScript.

2) Aponte o app macOS para o Gateway em execução

No OpenClaw.app:

  • Modo de Conexão: Local O app vai se conectar ao gateway rodando na porta configurada.

3) Verifique

  • O status do Gateway no app deve exibir “Using existing gateway …”
  • Ou via CLI:
openclaw health

Armadilhas comuns

  • Porta errada: O WS do Gateway usa por padrão ws://127.0.0.1:18789; mantenha app + CLI na mesma porta.
  • Onde os dados ficam:
    • Credenciais: ~/.openclaw/credentials/
    • Sessões: ~/.openclaw/agents/<agentId>/sessions/
    • Logs: /tmp/openclaw/

Mapa de armazenamento de credenciais

Use isso ao debugar autenticação ou decidir o que incluir no backup:

  • WhatsApp: ~/.openclaw/credentials/whatsapp/<accountId>/creds.json
  • Token do bot Telegram: config/env ou channels.telegram.tokenFile (apenas arquivo regular; symlinks são rejeitados)
  • Token do bot Discord: config/env ou SecretRef (provedores env/file/exec)
  • Tokens Slack: config/env (channels.slack.*)
  • Allowlists de pareamento:
    • ~/.openclaw/credentials/<channel>-allowFrom.json (conta padrão)
    • ~/.openclaw/credentials/<channel>-<accountId>-allowFrom.json (contas não-padrão)
  • Perfis de autenticação de modelo: ~/.openclaw/agents/<agentId>/agent/auth-profiles.json
  • Payload de secrets em arquivo (opcional): ~/.openclaw/secrets.json
  • Import legado de OAuth: ~/.openclaw/credentials/oauth.json Mais detalhes: Segurança.

Atualizando (sem quebrar seu setup)

  • Mantenha ~/.openclaw/workspace e ~/.openclaw/ como “suas coisas”; não coloque prompts/config pessoais dentro do repositório openclaw.
  • Atualizando o código-fonte: git pull + pnpm install (quando o lockfile mudar) + continue usando pnpm gateway:watch.

Linux (serviço systemd de usuário)

Instalações Linux usam um serviço systemd de usuário. Por padrão, o systemd para serviços de usuário ao fazer logout/idle, o que mata o Gateway. O onboarding tenta habilitar o lingering automaticamente (pode pedir sudo). Se ainda estiver desabilitado, rode:

sudo loginctl enable-linger $USER

Para servidores always-on ou multiusuário, considere um serviço de sistema em vez de serviço de usuário (sem necessidade de lingering). Veja o Runbook do Gateway para as notas sobre systemd.

Documentação relacionada

arrow_back
Anterior
Session Management Compaction
Próximo
Pi Dev
arrow_forward