​

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) guia você por:

• Configuração de modelo e autenticação (OAuth da assinatura OpenAI Code, Anthropic Claude CLI ou chave de API, além de opções para MiniMax, GLM, Ollama, Moonshot, StepFun 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, Mattermost, Signal, BlueBubbles e outros plugins de canal empacotados)
• Instalação do daemon (LaunchAgent, unidade de usuário do systemd ou Tarefa Agendada 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 autenticação do gateway remoto for obrigatória (recomendado)

​

Opções de autenticação e modelo

Comportamento do modelo:

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

Caminhos de credenciais e perfis:

• Perfis de autenticação (chaves de API + OAuth): ~/.openclaw/agents/<agentId>/agent/auth-profiles.json
• Importação OAuth legada: ~/.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 autenticação.
• --secret-input-mode ref habilita o modo de referência em vez do armazenamento da chave em texto simples. Na configuração interativa, você pode escolher:
  • ref de variável de ambiente (por exemplo keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" })
  • ref de provedor configurado (file ou exec) com alias + id do provedor
• O modo de referência interativo executa uma validação prévia rápida antes de salvar.
  • Refs de env: valida nome da variável + valor não vazio no ambiente atual do onboarding.
  • Refs de provedor: valida a configuração do provedor e resolve o id solicitado.
  • Se a validação prévia falhar, o onboarding mostra o erro e permite tentar de novo.
• No modo não interativo, --secret-input-mode ref é compatível apenas com env.
  • 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 essa variável esteja definida; caso contrário, o onboarding falha rapidamente.
  • Para provedores personalizados, o modo ref não interativo armazena models.providers.<id>.apiKey como { source: "env", provider: "default", id: "CUSTOM_API_KEY" }.
  • Nesse caso de provedor personalizado, --custom-api-key exige que CUSTOM_API_KEY esteja definido; caso contrário, o onboarding falha rapidamente.
• Credenciais de autenticação 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 detalhes internos

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 "coding" por padrão quando não definido; valores explícitos existentes são preservados)
• gateway.* (modo, bind, autenticação, tailscale)
• session.dmScope (o onboarding local define isso 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.matrix.*, channels.signal.*, channels.imessage.*
• Allowlists de canal (Slack, Discord, Matrix, Microsoft Teams) quando você opta por elas 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 UI de controle) podem renderizar etapas sem reimplementar a lógica do 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 do signal-cli do Linux dentro do WSL

​

Documentação relacionada

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