Referência de configuração da CLI

Esta página aborda o comportamento, as saídas e os componentes internos da integração inicial passo a passo. Para ver um passo a passo, consulte Integração inicial (CLI). Para obter a referência completa de flags da CLI (cada --flag, exemplos não interativos, comandos específicos de provedores), consulte openclaw onboard.

O que o assistente faz

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

• Configuração de modelo e autenticação (Anthropic, OAuth da assinatura OpenAI Code, xAI, OpenCode, endpoints personalizados e outros fluxos de autenticação pertencentes aos provedores)
• Local do espaço de trabalho e arquivos de inicialização
• Configurações do Gateway (porta, vinculação, autenticação, Tailscale)
• Canais e provedores (Discord, Feishu, Google Chat, iMessage, Mattermost, Microsoft Teams, QQ Bot, Signal, Slack, Telegram, WhatsApp e outros canais incluídos ou de plugins)
• Provedor de pesquisa na web (opcional)
• Instalação do daemon (LaunchAgent, unidade de usuário systemd ou Tarefa Agendada nativa do Windows com alternativa pela pasta Inicializar)
• Verificação de integridade
• Configuração de Skills

O modo remoto configura esta máquina para se conectar a um Gateway localizado 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 localizado em outro lugar. Ele não instala nem modifica nada no host remoto.

O que é configurado:

• URL do Gateway remoto (ws://... ou wss://...)
• Token, senha ou nenhuma autenticação, de acordo com a configuração do Gateway remoto

Opções de autenticação e modelo

Se uma etapa de configuração do provedor falhar durante a integração inicial interativa (por exemplo, uma opção de reutilização da CLI sem um login local), o assistente exibirá o erro e retornará ao seletor de provedores, em vez de encerrar. Execuções explícitas de --auth-choice ainda falham imediatamente para fins de automação.

Comportamento do modelo:

• Escolha o modelo padrão entre as opções detectadas ou informe manualmente o provedor e o modelo.
• Quando a integração começa a partir da escolha de autenticação de um provedor, o seletor de modelos dá preferência automaticamente a esse provedor. Para Volcengine e BytePlus, a mesma preferência também corresponde às variantes de planos de programação (volcengine-plan/*, byteplus-plan/*).
• Se esse filtro de provedor preferencial não retornar resultados, o seletor usa o catálogo completo como alternativa, em vez de não exibir nenhum modelo.
• O assistente executa uma verificação do modelo e avisa se o modelo configurado é desconhecido ou não possui autenticação.

Caminhos de credenciais e perfis:

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

Modo de armazenamento de credenciais:

• O comportamento padrão da integração mantém as 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 do armazenamento da chave em texto simples. Na configuração interativa, é possível 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 + ID do provedor
• O modo de referência interativo executa uma validação preliminar rápida antes de salvar.
  • Referências de variáveis de ambiente: valida o nome da variável + um valor não vazio no ambiente atual de integração.
  • Referências de provedores: valida a configuração do provedor e resolve o ID solicitado.
  • Se a validação preliminar falhar, a integração exibirá o erro e permitirá tentar novamente.
• No modo não interativo, --secret-input-mode ref é baseado somente em variável de ambiente.
  • Defina a variável de ambiente do provedor no ambiente do processo de integração.
  • Flags de chave em linha (por exemplo, --openai-api-key) exigem que essa variável de ambiente esteja definida; caso contrário, a integração falha imediatamente.
  • Para provedores personalizados, o modo não interativo ref 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 imediatamente.
• As credenciais de autenticação do Gateway permitem escolher entre texto simples e SecretRef na configuração interativa:
  • Modo de token: Gerar/armazenar token em texto simples (padrão) ou Usar SecretRef.
  • Modo de senha: texto simples ou SecretRef.
• Caminho SecretRef de token não interativo: --gateway-token-ref-env <ENV_VAR>.
• As 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 é fornecido
• agents.defaults.model / models.providers (se Minimax for escolhido)
• tools.profile (a integração local usa como padrão "coding" quando não definido; os valores explícitos existentes são preservados)
• gateway.* (modo, vínculo, autenticação, Tailscale)
• session.dmScope (a integração local usa como padrão per-channel-peer quando não definido; os 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 (Discord, iMessage, Signal, Slack, Telegram, WhatsApp) quando você aceita durante as solicitações; Discord e Slack também resolvem os nomes informados para IDs
• 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
• wizard.securityAcknowledgedAt

openclaw agents add grava agents.list[] e, opcionalmente, bindings.

As credenciais do WhatsApp ficam em ~/.openclaw/credentials/whatsapp/<accountId>/. As sessões ativas e as transcrições são armazenadas em ~/.openclaw/agents/<agentId>/agent/openclaw-agent.sqlite. O diretório ~/.openclaw/agents/<agentId>/sessions/ é usado para entradas de migração legada e artefatos de arquivamento/suporte.

Configuração não interativa

--non-interactive exige --accept-risk (confirma que os agentes são poderosos e que o acesso total ao sistema é arriscado):

openclaw onboard --non-interactive --accept-risk \  --auth-choice apiKey \  --anthropic-api-key "$ANTHROPIC_API_KEY"

Referência completa de flags e exemplos específicos de provedores: openclaw onboard, Automação da CLI.

RPC do assistente do Gateway

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

Os clientes (aplicativo para macOS e interface de controle) podem renderizar as etapas sem reimplementar a lógica de integração.

Comportamento da configuração do Signal

• Baixa o artefato de versão apropriado das versões oficiais do GitHub de signal-cli (compilação nativa, somente Linux x86-64)
• Em outras plataformas (macOS, Linux não x64), instala pelo Homebrew
• Armazena a instalação do artefato de versão em ~/.openclaw/tools/signal-cli/<version>/
• Grava channels.signal.cliPath na configuração
• O Windows nativo ainda não é compatível; execute a integração no WSL2 para obter o caminho de instalação do Linux

Documentação relacionada

• Central de integração: Integração (CLI)
• Automação e scripts: Automação da CLI
• Referência do comando: openclaw onboard