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ê por:

• Configuração de modelo e autenticação (OAuth da assinatura OpenAI Code, CLI ou chave de API do Anthropic Claude, além de opções MiniMax, GLM, Ollama, Moonshot, StepFun e AI Gateway)
• Local 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 incluídos)
• Instalação do daemon (LaunchAgent, unidade de usuário systemd ou Tarefa Agendada nativa do Windows com fallback para a pasta Inicializar)
• 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ê configura:

• 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.
• O onboarding de provedor personalizado infere suporte a imagem para IDs de modelo comuns e pergunta apenas quando o nome do modelo é desconhecido.
• Quando o onboarding começa a partir de uma opção de autenticação de provedor, o seletor de modelo prefere esse provedor 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 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 de 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 de onboarding persiste chaves de API como valores em texto simples nos perfis de autenticação.
• --secret-input-mode ref ativa o modo de referência em vez de armazenamento de 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 do provedor + id
• O modo de referência interativo executa uma validação rápida de pré-voo antes de salvar.
  • Refs de env: valida o nome da variável + valor não vazio no ambiente atual de onboarding.
  • Refs de provedor: valida a configuração do provedor e resolve o id solicitado.
  • Se o pré-voo falhar, o onboarding mostra o erro e permite tentar novamente.
• No modo não interativo, --secret-input-mode ref é baseado apenas em env.
  • Defina a variável de ambiente do provedor no ambiente do processo de onboarding.
  • Flags de chave embutidas (por exemplo --openai-api-key) exigem que essa variável de ambiente 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.
• As 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 alterações.

# Saídas e detalhes internos

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

• agents.defaults.workspace
• agents.defaults.skipBootstrap quando --skip-bootstrap é passado
• 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.*
• Listas de permissões de canais (Slack, Discord, Matrix, Microsoft Teams) quando você opta por elas durante os prompts (os 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" posteriormente.
• 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 (aplicativo macOS e Control UI) podem renderizar etapas sem reimplementar a lógica de onboarding.

Comportamento de configuração do Signal:

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

# Documentos relacionados

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