Referência de Onboarding CLI

Esta pagina e a referência completa do openclaw onboard. Para o guia resumido, veja Assistente de Onboarding (CLI).

O que o assistente faz

O modo local (padrão) guia você por:

• Setup de modelo e autenticação (OAuth de assinatura OpenAI Code, chave de API Anthropic ou setup token, além de opções MiniMax, GLM, Ollama, Moonshot e AI Gateway)
• Localização do workspace e arquivos de bootstrap
• Configurações do Gateway (porta, bind, autenticação, tailscale)
• Canais e provedores (Telegram, WhatsApp, Discord, Google Chat, plugin Mattermost, Signal)
• Instalação do daemon (LaunchAgent ou unidade systemd de usuário)
• Health check
• Setup de skills

O modo remoto configura esta máquina para se conectar a um gateway em outro lugar. Ele não instala nem modifica nada no host remoto.

Detalhes do fluxo local

Passo 1: Detecção de configuração existente

- Se `~/.openclaw/openclaw.json` existir, escolha Manter, Modificar ou Resetar.
- Re-executar o assistente não apaga nada a menos que você escolha explicitamente Resetar (ou passe `--reset`).
- O `--reset` via CLI aplica por padrão `config+creds+sessions`; use `--reset-scope full` para remover o workspace também.
- Se a config for inválida ou contiver chaves legadas, o assistente para e pede para você executar `openclaw doctor` antes de continuar.
- O reset usa `trash` e oferece escopos:
  - Apenas config
  - Config + credenciais + sessões
  - Reset completo (também remove o workspace)

Passo 2: Modelo e autenticação

- A matriz completa de opções está em [Opções de auth e modelo](#opções-de-auth-e-modelo).

Passo 3: Workspace

- Padrão `~/.openclaw/workspace` (configurável).
- Gera os arquivos de workspace necessários para o ritual de bootstrap da primeira execução.
- Layout do workspace: [Workspace do agente](/docs/concepts/agent-workspace).

Passo 4: Gateway

- Solicita porta, bind, modo de autenticação e exposição tailscale.
- Recomendado: mantenha autenticação por token habilitada mesmo em loopback para que clientes WS locais precisem se autenticar.
- No modo de token, o onboarding interativo oferece:
  - **Gerar/armazenar token em texto plano** (padrão)
  - **Usar SecretRef** (opt-in)
- No modo de senha, o onboarding interativo também suporta armazenamento em texto plano ou SecretRef.
- Caminho de SecretRef de token não-interativo: `--gateway-token-ref-env <ENV_VAR>`.
  - Requer uma variável de ambiente não vazia no ambiente do processo de onboarding.
  - Não pode ser combinado com `--gateway-token`.
- Desabilite a autenticação apenas se confiar totalmente em todo processo local.
- Binds que não sejam loopback ainda exigem autenticação.

Passo 5: Canais

- [WhatsApp](/docs/channels/whatsapp): login via QR opcional
- [Telegram](/docs/channels/telegram): token do bot
- [Discord](/docs/channels/discord): token do bot
- [Google Chat](/docs/channels/googlechat): JSON de service account + audience do webhook
- [Mattermost](/docs/channels/mattermost) plugin: token do bot + URL base
- [Signal](/docs/channels/signal): instalação opcional do `signal-cli` + configuração de conta
- [BlueBubbles](/docs/channels/bluebubbles): recomendado para iMessage; URL do servidor + senha + webhook
- [iMessage](/docs/channels/imessage): legado, caminho do CLI `imsg` + acesso ao DB
- Segurança de DMs: o padrão é pareamento. A primeira DM envia um código; aprove via
  `openclaw pairing approve <channel> <code>` ou use allowlists.

Passo 6: Instalação do daemon

- macOS: LaunchAgent
  - Requer sessão de usuário logado; para headless, use um LaunchDaemon customizado (não incluso).
- Linux e Windows via WSL2: unidade systemd de usuário
  - O assistente tenta `loginctl enable-linger <user>` para que o gateway continue rodando após logout.
  - Pode pedir sudo (escreve em `/var/lib/systemd/linger`); tenta sem sudo primeiro.
- Seleção de runtime: Node (recomendado; obrigatório para WhatsApp e Telegram). Bun não é recomendado.

Passo 7: Health check

- Inicia o gateway (se necessário) e executa `openclaw health`.
- `openclaw status --deep` adiciona probes de health do gateway na saída de status.

Passo 8: Skills

- Lê as skills disponíveis e verifica requisitos.
- Permite escolher o gerenciador de pacotes: npm ou pnpm (bun não recomendado).
- Instala dependências opcionais (algumas usam Homebrew no macOS).

Passo 9: Finalização

- Resumo e próximos passos, incluindo opções de apps iOS, Android e macOS.

Nota: Se nenhuma interface gráfica for detectada, o assistente imprime instruções de port-forward SSH para a Control UI em vez de abrir um navegador. Se os assets da Control UI estiverem faltando, o assistente tenta fazer o build; fallback é pnpm ui:build (instala dependências da UI automaticamente).

Detalhes do modo remoto

O modo remoto configura esta máquina para se conectar a um gateway em outro lugar.

Info: O modo remoto não instala nem modifica nada no host remoto.

O que você configura:

• URL do gateway remoto (ws://...)
• Token se a autenticação do gateway remoto for obrigatória (recomendado)

Nota:

• Se o gateway estiver em loopback-only, use tunelamento SSH ou uma tailnet.
• Dicas de discovery:
  • macOS: Bonjour (dns-sd)
  • Linux: Avahi (avahi-browse)

Opções de auth e modelo

Usa `ANTHROPIC_API_KEY` se presente ou solicita uma chave, depois salva para uso do daemon.

- macOS: verifica item do Keychain "Claude Code-credentials"
- Linux e Windows: reutiliza `~/.claude/.credentials.json` se presente

No macOS, escolha "Always Allow" para que starts via launchd não fiquem bloqueados.

Execute `claude setup-token` em qualquer máquina, depois cole o token.
Pode dar um nome; deixe em branco para usar o padrão.

Se `~/.codex/auth.json` existir, o assistente pode reutilizá-lo.

Fluxo pelo navegador; cole `code#state`.

Define `agents.defaults.model` como `openai-codex/gpt-5.4` quando o modelo não está definido ou é `openai/*`.

Usa `OPENAI_API_KEY` se presente ou solicita uma chave, depois armazena a credencial nos perfis de autenticação.

Define `agents.defaults.model` como `openai/gpt-5.1-codex` quando o modelo não está definido, é `openai/*` ou `openai-codex/*`.

Solicita `XAI_API_KEY` e configura xAI como provedor de modelo.

Solicita `OPENCODE_API_KEY` (ou `OPENCODE_ZEN_API_KEY`) e permite escolher o catálogo Zen ou Go.
URL de setup: [opencode.ai/auth](https://opencode.ai/auth).

Armazena a chave para você.

Solicita `AI_GATEWAY_API_KEY`.
Mais detalhes: [Vercel AI Gateway](/docs/providers/vercel-ai-gateway).

Solicita account ID, gateway ID e `CLOUDFLARE_AI_GATEWAY_API_KEY`.
Mais detalhes: [Cloudflare AI Gateway](/docs/providers/cloudflare-ai-gateway).

Configuração é gravada automaticamente.
Mais detalhes: [MiniMax](/docs/providers/minimax).

Solicita `SYNTHETIC_API_KEY`.
Mais detalhes: [Synthetic](/docs/providers/synthetic).

Solicita URL base (padrão `http://127.0.0.1:11434`), depois oferece modo Cloud + Local ou apenas Local.
Descobre modelos disponíveis e sugere padrões.
Mais detalhes: [Ollama](/docs/providers/ollama).

Configurações do Moonshot (Kimi K2) e Kimi Coding são gravadas automaticamente.
Mais detalhes: [Moonshot AI (Kimi + Kimi Coding)](/docs/providers/moonshot).

Funciona com endpoints compatíveis com OpenAI e Anthropic.

O onboarding interativo suporta as mesmas opções de armazenamento de chave de API que os outros fluxos de provedor:
- **Colar chave de API agora** (texto plano)
- **Usar referência de secret** (referência de variável de ambiente ou referência de provedor configurado, com validação prévia)

Flags não-interativas:
- `--auth-choice custom-api-key`
- `--custom-base-url`
- `--custom-model-id`
- `--custom-api-key` (opcional; fallback para `CUSTOM_API_KEY`)
- `--custom-provider-id` (opcional)
- `--custom-compatibility <openai|anthropic>` (opcional; padrão `openai`)

Deixa a autenticação sem configurar.

Comportamento de modelo:

• Escolha o modelo padrão entre as opções detectadas ou informe provedor e modelo manualmente.
• O assistente executa uma verificação de modelo e avisa se o modelo configurado for desconhecido ou sem autenticação.

Caminhos de credenciais e perfis:

• Credenciais OAuth: ~/.openclaw/credentials/oauth.json
• Perfis de autenticação (chaves de API + OAuth): ~/.openclaw/agents/<agentId>/agent/auth-profiles.json

Modo de armazenamento de credenciais:

• O comportamento padrão do onboarding persiste chaves de API como valores em texto plano nos perfis de autenticação.
• --secret-input-mode ref habilita o modo de referência em vez de armazenamento em texto plano. No onboarding interativo, você pode escolher:
  • referência de variável de ambiente (por exemplo keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" })
  • referência de provedor configurado (file ou exec) com alias do provedor + id
• O modo interativo de referência executa uma validação prévia rápida antes de salvar.
  • Referências de variável de ambiente: valida o nome da variável + valor não vazio no ambiente atual de onboarding.
  • Referências de provedor: valida a configuração do provedor e resolve o id solicitado.
  • Se a validação falhar, o onboarding mostra o erro e permite tentar novamente.
• No modo não-interativo, --secret-input-mode ref funciona apenas com variáveis de ambiente.
  • Defina a variável de ambiente do provedor no ambiente do processo de onboarding.
  • Flags de chave inline (por exemplo --openai-api-key) exigem que a variável de ambiente esteja definida; caso contrário, o onboarding falha imediatamente.
  • Para provedores customizados, o modo ref não-interativo armazena models.providers.<id>.apiKey como { source: "env", provider: "default", id: "CUSTOM_API_KEY" }.
  • Nesse caso de provedor customizado, --custom-api-key exige que CUSTOM_API_KEY esteja definida; caso contrário, o onboarding falha imediatamente.
• Credenciais de autenticação do Gateway suportam texto plano e SecretRef no onboarding interativo:
  • Modo token: Gerar/armazenar token em texto plano (padrão) ou Usar SecretRef.
  • Modo senha: texto plano ou SecretRef.
• Caminho de SecretRef de token não-interativo: --gateway-token-ref-env <ENV_VAR>.
• Setups existentes em texto plano continuam funcionando sem alterações.

Nota: Dica para servidores headless: complete o OAuth numa máquina com navegador, depois copie ~/.openclaw/credentials/oauth.json (ou $OPENCLAW_STATE_DIR/credentials/oauth.json) para o host do gateway.

Outputs e internos

Campos típicos em ~/.openclaw/openclaw.json:

• agents.defaults.workspace
• agents.defaults.model / models.providers (se MiniMax for escolhido)
• tools.profile (onboarding local define como "coding" por padrão quando não definido; valores explícitos existentes são preservados)
• gateway.* (modo, bind, autenticação, tailscale)
• session.dmScope (onboarding local define como per-channel-peer por padrão quando não definido; valores explícitos existentes são preservados)
• channels.telegram.botToken, channels.discord.token, channels.signal.*, channels.imessage.*
• Allowlists de canais (Slack, Discord, Matrix, Microsoft Teams) quando você opta durante as perguntas (nomes são resolvidos para IDs quando possível)
• skills.install.nodeManager
• wizard.lastRunAt
• wizard.lastRunVersion
• wizard.lastRunCommit
• wizard.lastRunCommand
• wizard.lastRunMode

openclaw agents add grava agents.list[] e bindings opcionais.

Credenciais do WhatsApp ficam em ~/.openclaw/credentials/whatsapp/<accountId>/. Sessões são armazenadas em ~/.openclaw/agents/<agentId>/sessions/.

Nota: Alguns canais são entregues como plugins. Quando selecionados durante o onboarding, o assistente solicita a instalação do plugin (npm ou caminho local) antes da configuração do canal.

RPC do assistente de Gateway:

• wizard.start
• wizard.next
• wizard.cancel
• wizard.status

Clientes (app macOS e Control UI) podem renderizar as etapas sem reimplementar a lógica de onboarding.

Comportamento do setup do Signal:

• Baixa o asset de release apropriado
• Armazena em ~/.openclaw/tools/signal-cli/<version>/
• Grava channels.signal.cliPath na config
• Builds JVM exigem Java 21
• Builds nativos são usados quando disponíveis
• Windows usa WSL2 e segue o fluxo do signal-cli para Linux dentro do WSL

Documentação relacionada

• Hub de onboarding: Assistente de Onboarding (CLI)
• Automação e scripts: Automação CLI
• Referência de comando: openclaw onboard