Referência de configuração da CLI

Esta página aborda, passo a passo, o comportamento, as saídas e os detalhes internos da integração inicial. Para ver um passo a passo, consulte Integração inicial (CLI). Para obter a referência completa de sinalizadores da CLI (todos os --flag, exemplos não interativos e 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 do OpenAI Code, xAI, OpenCode, endpoints personalizados e outros fluxos de autenticação gerenciados pelos 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 integrados 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 em outro local. 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 local. Ele não instala nem modifica nada no host remoto.

O que você configura:

• 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 configuração inicial interativa (por exemplo, uma opção de reutilização da CLI sem login local), o assistente exibirá o erro e retornará ao seletor de provedores, em vez de encerrar. Execuções explícitas com --auth-choice ainda falham imediatamente para permitir 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 plano de programação (volcengine-plan/*, byteplus-plan/*).
• Se esse filtro de provedor preferencial não retornar resultados, o seletor usa o catálogo completo em vez de não exibir nenhum modelo.
• O assistente executa uma verificação do modelo e avisa se o modelo configurado for desconhecido ou não tiver 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:

• Por padrão, a integração persiste 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, você pode 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 do provedor + ID
• O modo de referência interativo executa uma validação prévia rápida antes de salvar.
  • Referências de variável de ambiente: valida o nome da variável e a existência de um valor não vazio no ambiente atual da integração.
  • Referências de provedor: valida a configuração do provedor e resolve o ID solicitado.
  • Se a validação prévia falhar, a integração exibe o erro e permite tentar novamente.
• No modo não interativo, --secret-input-mode ref aceita somente variáveis 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 definida; 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 não interativo para SecretRef do token: --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 é fornecida
• agents.defaults.model / models.providers (se Minimax for escolhido)
• tools.profile (a integração local usa "coding" como padrão quando não definido; valores explícitos existentes são preservados)
• gateway.* (modo, vinculação, autenticação, Tailscale)
• session.dmScope (a integração local usa per-channel-peer como 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 (Discord, iMessage, Signal, Slack, Telegram, WhatsApp) quando você aceita durante as solicitações; Discord e Slack também resolvem os nomes informados em IDs
• skills.install.nodeManager
  • A flag setup --node-manager aceita npm, pnpm ou bun.
  • Posteriormente, a configuração manual ainda pode definir skills.install.nodeManager: "yarn".
• wizard.lastRunAt
• wizard.lastRunVersion
• wizard.lastRunCommit
• wizard.lastRunCommand
• wizard.lastRunMode
• wizard.securityAcknowledgedAt

openclaw agents add grava agents.list[] e bindings opcionais.

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 legadas e artefatos de arquivamento/suporte.

Configuração não interativa

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

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

Referência completa das 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 signal-cli no GitHub (compilação nativa, somente Linux x86-64)
• Em outras plataformas (macOS e Linux não x64), instala via 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