Assistente de Onboarding (CLI)

O assistente de onboarding e a forma recomendada de configurar o OpenClaw no macOS, Linux ou Windows (via WSL2; fortemente recomendado). Ele configura um Gateway local ou uma conexão com Gateway remoto, alem de canais, skills e padrões de workspace num fluxo guiado.

openclaw onboard

Info: Chat mais rápido: abra a Control UI (sem precisar configurar canais). Execute openclaw dashboard e converse pelo navegador. Docs: Dashboard.

Para reconfigurar depois:

openclaw configure
openclaw agents add <name>

Nota: --json não implica modo não-interativo. Para scripts, use --non-interactive.

Dica: O assistente de onboarding inclui uma etapa de busca web onde você pode escolher um provedor (Perplexity, Brave, Gemini, Grok ou Kimi) e colar sua chave de API para que o agente possa usar web_search. Você também pode configurar isso depois com openclaw configure --section web. Docs: Ferramentas web.

QuickStart vs Avançado

O assistente começa oferecendo QuickStart (padrões) vs Avançado (controle total).

QuickStart (padrões)

- Gateway local (loopback)
- Workspace padrão (ou workspace existente)
- Porta do Gateway **18789**
- Autenticação do Gateway **Token** (gerado automaticamente, mesmo em loopback)
- Política de ferramentas padrão para novos setups locais: `tools.profile: "coding"` (perfil explícito existente é preservado)
- Isolamento de DM padrão: o onboarding local grava `session.dmScope: "per-channel-peer"` quando não definido. Detalhes: [Referência de Onboarding CLI](/docs/start/wizard-cli-reference#outputs-and-internals)
- Exposição Tailscale **Desligada**
- DMs no Telegram + WhatsApp em modo **allowlist** por padrão (será solicitado seu número de telefone)

Avançado (controle total)

- Expõe todas as etapas (modo, workspace, gateway, canais, daemon, skills).

O que o assistente configura

Modo local (padrão) guia você por estas etapas:

  1. Modelo/Auth — escolha qualquer provedor/fluxo de autenticação suportado (chave de API, OAuth ou setup-token), incluindo Custom Provider (compatível com OpenAI, compatível com Anthropic ou auto-detect Unknown). Escolha um modelo padrão. Nota de segurança: se este agente vai executar ferramentas ou processar conteúdo de webhook/hooks, prefira o modelo mais forte de última geração disponível e mantenha a política de ferramentas restrita. Modelos mais fracos/antigos são mais fáceis de sofrer prompt-injection. Para execuções não-interativas, --secret-input-mode ref armazena referências baseadas em variáveis de ambiente nos perfis de autenticação em vez de valores de chave em texto plano. No modo ref não-interativo, a variável de ambiente do provedor precisa estar definida; passar flags de chave inline sem essa variável falha imediatamente. Em execuções interativas, escolher o modo de referência de secret permite apontar para uma variável de ambiente ou uma referência de provedor configurada (file ou exec), com validação prévia rápida antes de salvar.
  2. Workspace — Local dos arquivos do agente (padrão ~/.openclaw/workspace). Gera os arquivos de bootstrap.
  3. Gateway — Porta, endereço de bind, modo de autenticação, exposição Tailscale. No modo de token interativo, escolha entre armazenamento de token em texto plano (padrão) ou SecretRef. Caminho de SecretRef de token não-interativo: --gateway-token-ref-env <ENV_VAR>.
  4. Canais — WhatsApp, Telegram, Discord, Google Chat, Mattermost, Signal, BlueBubbles ou iMessage.
  5. Daemon — Instala um LaunchAgent (macOS) ou unidade systemd de usuário (Linux/WSL2). Se a autenticação por token exigir um token e gateway.auth.token for gerenciado por SecretRef, a instalação do daemon valida mas não persiste o token resolvido nos metadados do ambiente do serviço supervisor. Se a autenticação por token exigir um token e o SecretRef configurado não estiver resolvido, a instalação do daemon é bloqueada com orientações de ação. Se ambos gateway.auth.token e gateway.auth.password estiverem configurados e gateway.auth.mode não estiver definido, a instalação do daemon e bloqueada até que o modo seja definido explicitamente.
  6. Health check — Inicia o Gateway e verifica se está rodando.
  7. Skills — Instala skills recomendadas e dependências opcionais.

Nota: Re-executar o assistente não apaga nada a menos que você escolha explicitamente Reset (ou passe --reset). O --reset via CLI aplica por padrão a config, credenciais e sessões; use --reset-scope full para incluir o workspace. Se a config for inválida ou contiver chaves legadas, o assistente pede para você executar openclaw doctor primeiro.

Modo remoto configura apenas o cliente local para se conectar a um Gateway em outro lugar. Ele não instala nem altera nada no host remoto.

Adicionar outro agente

Use openclaw agents add <name> para criar um agente separado com workspace, sessões e perfis de autenticação próprios. Executar sem --workspace abre o assistente.

O que ele define:

  • agents.list[].name
  • agents.list[].workspace
  • agents.list[].agentDir

Observações:

  • Workspaces padrão seguem ~/.openclaw/workspace-<agentId>.
  • Adicione bindings para rotear mensagens de entrada (o assistente pode fazer isso).
  • Flags não-interativas: --model, --agent-dir, --bind, --non-interactive.

Referência completa

Para detalhamentos passo a passo e outputs de configuração, veja Referência de Onboarding CLI. Para exemplos não-interativos, veja Automação CLI. Para a referência técnica mais profunda, incluindo detalhes de RPC, veja Referência do Wizard.

Documentação relacionada

arrow_back
Anterior
Onboarding Overview
Próximo
Onboarding
arrow_forward