​

Referência de configuração da CLI

Esta página é a referência completa para openclaw onboard. Para o guia curto, consulte Onboarding (CLI).

​

O que o assistente faz

O modo local (padrão) orienta você em:

• Configuração de modelo e auth (OAuth de assinatura do OpenAI Code, Anthropic Claude CLI ou chave de API, além de opções para MiniMax, GLM, Ollama, Moonshot, StepFun e AI Gateway)
• Local do workspace e arquivos de bootstrap
• Configurações do gateway (porta, bind, auth, tailscale)
• Canais e providers (Telegram, WhatsApp, Discord, Google Chat, Mattermost, Signal, BlueBubbles e outros plugins de canal empacotados)
• Instalação como daemon (LaunchAgent, unit de usuário do systemd ou Scheduled Task nativa do Windows com fallback para a pasta Startup)
• Verificação de integridade
• Configuração 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

​

Detalhes do modo remoto

O modo remoto configura esta máquina para se conectar a um gateway em outro lugar. O que você define:

• URL do gateway remoto (ws://...)
• Token se a auth do gateway remoto for necessária (recomendado)

​

Opções de auth e modelo

Comportamento do modelo:

• Escolha o modelo padrão entre as opções detectadas, ou informe manualmente o provider e o modelo.
• Quando o onboarding começa a partir de uma escolha de auth de provider, o seletor de modelos passa a priorizar esse provider automaticamente. Para Volcengine e BytePlus, a mesma preferência também corresponde às variantes de plano de codificação (volcengine-plan/*, byteplus-plan/*).
• Se esse filtro de provider preferido ficar vazio, o seletor volta para o catálogo completo em vez de mostrar nenhum modelo.
• O assistente executa uma verificação do modelo e avisa se o modelo configurado for desconhecido ou estiver sem auth.

Caminhos de credenciais e perfis:

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

Modo de armazenamento de credenciais:

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

​

Saídas e internals

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

• agents.defaults.workspace
• agents.defaults.model / models.providers (se MiniMax for escolhido)
• tools.profile (o onboarding local usa por padrão "coding" quando não está definido; valores explícitos existentes são preservados)
• gateway.* (mode, bind, auth, tailscale)
• session.dmScope (o onboarding local usa por padrão per-channel-peer quando não está definido; valores explícitos existentes são preservados)
• channels.telegram.botToken, channels.discord.token, channels.matrix.*, channels.signal.*, channels.imessage.*
• Allowlists de canal (Slack, Discord, Matrix, Microsoft Teams) quando você opta por isso durante os prompts (nomes são resolvidos para IDs quando possível)
• skills.install.nodeManager
  • A flag setup --node-manager aceita npm, pnpm ou bun.
  • A configuração manual ainda pode definir skills.install.nodeManager: "yarn" depois.
• wizard.lastRunAt
• wizard.lastRunVersion
• wizard.lastRunCommit
• wizard.lastRunCommand
• wizard.lastRunMode

openclaw agents add grava agents.list[] e bindings opcionais. As credenciais do WhatsApp ficam em ~/.openclaw/credentials/whatsapp/<accountId>/. As sessões são armazenadas em ~/.openclaw/agents/<agentId>/sessions/. RPC do assistente do gateway:

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

Clientes (app do macOS e Control UI) podem renderizar etapas sem reimplementar a lógica de onboarding. Comportamento da configuração do Signal:

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

​

Documentação relacionada

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