Referência de configuração da CLI

Esta página é a referência completa para openclaw onboard. Para o guia curto, consulte Integração (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 Anthropic Claude ou chave de API, 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, iMessage e outros plugins de canal incluídos)
• Instalação do daemon (LaunchAgent, unidade systemd de usuário 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ê define:

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

Opções de autenticação e modelo

Comportamento do modelo:

• Escolha o modelo padrão a partir das opções detectadas ou insira provedor e modelo manualmente.
• A integração de provedor personalizado infere suporte a imagem para IDs de modelo comuns e pergunta somente quando o nome do modelo é desconhecido.
• Quando a integração 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 suas variantes de plano de codificação (volcengine-plan/*, byteplus-plan/*).
• Se esse filtro de provedor preferido ficar vazio, o seletor faz fallback 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 não tem 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 da integração 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 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 prévia rápida antes de salvar.
  • Refs de env: valida nome da variável + valor não vazio no ambiente atual da integração.
  • Refs de provedor: valida a configuração do provedor e resolve o id solicitado.
  • Se a validação prévia falhar, a integração mostra o erro e permite tentar novamente.
• No modo não interativo, --secret-input-mode ref é apoiado somente por env.
  • Defina a variável de ambiente do provedor no ambiente do processo de integração.
  • Flags de chave inline (por exemplo --openai-api-key) exigem que essa variável de ambiente esteja definida; caso contrário, a integração 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, a integração falha rapidamente.
• Credenciais de autenticação do Gateway oferecem suporte a 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 componentes 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.* (mode, bind, auth, 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ão de canais (Slack, Discord, Matrix, Microsoft Teams) quando você opta por usá-las 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.

Credenciais do WhatsApp ficam em ~/.openclaw/credentials/whatsapp/<accountId>/. 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 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-o em ~/.openclaw/tools/signal-cli/<version>/
• Grava channels.signal.cliPath na configuração
• Builds da JVM exigem Java 21
• Builds nativas são usadas quando disponíveis
• Windows usa WSL2 e segue o fluxo do signal-cli para Linux dentro do WSL

Documentos relacionados

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