English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this pageOpen in PerplexityAsk questions about this page

Technical reference

Referência de integração inicial

Esta é a referência completa para openclaw onboard. Para uma visão geral de alto nível, consulte Onboarding (CLI).

Detalhes do fluxo (modo local)

  • Detecção de configuração existente

    • Se ~/.openclaw/openclaw.json existir, escolha Manter valores atuais, Revisar e atualizar ou Redefinir antes da configuração.
    • Executar o onboarding novamente não apaga nada, a menos que você escolha explicitamente Redefinir (ou passe --reset).
    • CLI --reset usa config+creds+sessions por padrão; use --reset-scope full para também remover o workspace.
    • Se a configuração for inválida ou contiver chaves legadas, o assistente para e solicita que você execute openclaw doctor antes de continuar.
    • A redefinição usa trash (nunca rm) e oferece escopos:
      • Somente configuração
      • Configuração + credenciais + sessões
      • Redefinição completa (também remove o workspace)

  • Modelo/Auth

    • Chave de API da Anthropic: usa ANTHROPIC_API_KEY se estiver presente ou solicita uma chave, depois a salva para uso do daemon.
    • Chave de API da Anthropic: escolha preferida de assistente Anthropic no onboarding/configure.
    • setup-token da Anthropic: ainda disponível no onboarding/configure, embora o OpenClaw agora prefira reutilizar a Claude CLI quando disponível.
    • Assinatura OpenAI Code (Codex) (OAuth): fluxo no navegador; cole o code#state.
      • Define agents.defaults.model como openai/gpt-5.5 por meio do runtime Codex quando o modelo não está definido ou já é da família OpenAI.
    • Assinatura OpenAI Code (Codex) (pareamento de dispositivo): fluxo de pareamento no navegador com um código de dispositivo de curta duração.
      • Define agents.defaults.model como openai/gpt-5.5 por meio do runtime Codex quando o modelo não está definido ou já é da família OpenAI.
    • Chave de API da OpenAI: usa OPENAI_API_KEY se estiver presente ou solicita uma chave, depois a armazena em perfis de auth.
      • Define agents.defaults.model como openai/gpt-5.5 quando o modelo não está definido, é openai/* ou openai-codex/*.
    • Chave de API da xAI (Grok): solicita XAI_API_KEY e configura a xAI como provedora de modelo.
    • OpenCode: solicita OPENCODE_API_KEY (ou OPENCODE_ZEN_API_KEY, obtenha em https://opencode.ai/auth) e permite escolher o catálogo Zen ou Go.
    • Ollama: oferece primeiro Nuvem + Local, Somente nuvem ou Somente local. Cloud only solicita OLLAMA_API_KEY e usa https://ollama.com; os modos apoiados por host solicitam a URL base do Ollama, descobrem os modelos disponíveis e baixam automaticamente o modelo local selecionado quando necessário; Cloud + Local também verifica se esse host Ollama está conectado para acesso à nuvem.
    • Mais detalhes: Ollama
    • Chave de API: armazena a chave para você.
    • Vercel AI Gateway (proxy multimodelo): solicita AI_GATEWAY_API_KEY.
    • Mais detalhes: Vercel AI Gateway
    • Cloudflare AI Gateway: solicita ID da conta, ID do Gateway e CLOUDFLARE_AI_GATEWAY_API_KEY.
    • Mais detalhes: Cloudflare AI Gateway
    • MiniMax: a configuração é gravada automaticamente; o padrão hospedado é MiniMax-M2.7. A configuração com chave de API usa minimax/..., e a configuração OAuth usa minimax-portal/....
    • Mais detalhes: MiniMax
    • StepFun: a configuração é gravada automaticamente para StepFun standard ou Step Plan em endpoints da China ou globais.
    • Atualmente, Standard inclui step-3.5-flash, e Step Plan também inclui step-3.5-flash-2603.
    • Mais detalhes: StepFun
    • Synthetic (compatível com Anthropic): solicita SYNTHETIC_API_KEY.
    • Mais detalhes: Synthetic
    • Moonshot (Kimi K2): a configuração é gravada automaticamente.
    • Kimi Coding: a configuração é gravada automaticamente.
    • Mais detalhes: Moonshot AI (Kimi + Kimi Coding)
    • Pular: nenhuma auth configurada ainda.
    • Escolha um modelo padrão entre as opções detectadas (ou informe provedor/modelo manualmente). Para obter a melhor qualidade e menor risco de injeção de prompt, escolha o modelo mais forte da geração mais recente disponível na sua pilha de provedores.
    • O onboarding executa uma verificação de modelo e alerta se o modelo configurado for desconhecido ou não tiver auth.
    • O modo de armazenamento de chave de API usa valores de perfil de auth em texto simples por padrão. Use --secret-input-mode ref para armazenar refs baseadas em env (por exemplo, keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" }).
    • Perfis de auth ficam em ~/.openclaw/agents/<agentId>/agent/auth-profiles.json (chaves de API + OAuth). ~/.openclaw/credentials/oauth.json é apenas importação legada.
    • Mais detalhes: /concepts/oauth

  • Workspace

    • Padrão ~/.openclaw/workspace (configurável).
    • Inicializa os arquivos de workspace necessários para o ritual de bootstrap do agente.
    • Layout completo do workspace + guia de backup: Workspace do agente

  • Gateway

    • Porta, bind, modo de auth, exposição via Tailscale.
    • Recomendação de auth: mantenha Token mesmo para loopback, para que clientes WS locais precisem se autenticar.
    • No modo token, a configuração interativa oferece:
      • Gerar/armazenar token em texto simples (padrão)
      • Usar SecretRef (opt-in)
      • O Quickstart reutiliza SecretRefs gateway.auth.token existentes nos provedores env, file e exec para a sonda de onboarding/bootstrap do painel.
      • Se esse SecretRef estiver configurado, mas não puder ser resolvido, o onboarding falha cedo com uma mensagem clara de correção em vez de degradar silenciosamente a auth em runtime.
    • No modo senha, a configuração interativa também oferece suporte a armazenamento em texto simples ou SecretRef.
    • Caminho SecretRef de token não interativo: --gateway-token-ref-env &lt;ENV_VAR&gt;.
      • Exige uma variável de ambiente não vazia no ambiente do processo de onboarding.
      • Não pode ser combinado com --gateway-token.
    • Desative a auth apenas se você confiar plenamente em todos os processos locais.
    • Binds que não sejam loopback ainda exigem auth.

  • Canais

    • WhatsApp: login opcional por QR.
    • Telegram: token do bot.
    • Discord: token do bot.
    • Google Chat: JSON da conta de serviço + público do webhook.
    • Mattermost (Plugin): token do bot + URL base.
    • Signal: instalação opcional do signal-cli + configuração da conta.
    • iMessage: caminho da CLI imsg + acesso ao banco de dados do Messages; use um wrapper SSH quando o Gateway rodar fora do Mac.
    • Segurança de DM: o padrão é pareamento. A primeira DM envia um código; aprove via openclaw pairing approve <channel> <code> ou use listas de permissão.

  • Pesquisa na web

    • Escolha um provedor com suporte, como Brave, DuckDuckGo, Exa, Firecrawl, Gemini, Grok, Kimi, MiniMax Search, Ollama Web Search, Perplexity, SearXNG ou Tavily (ou pule).
    • Provedores baseados em API podem usar variáveis de ambiente ou configuração existente para configuração rápida; provedores sem chave usam seus pré-requisitos específicos de provedor.
    • Pule com --skip-search.
    • Configure depois: openclaw configure --section web.

  • Instalação do daemon

    • macOS: LaunchAgent
      • Exige uma sessão de usuário conectada; para headless, use um LaunchDaemon personalizado (não distribuído).
    • Linux (e Windows via WSL2): unidade de usuário systemd
      • O onboarding tenta habilitar lingering via loginctl enable-linger <user> para que o Gateway permaneça ativo após logout.
      • Pode solicitar sudo (grava em /var/lib/systemd/linger); ele tenta sem sudo primeiro.
    • Seleção de runtime: Node (recomendado; necessário para WhatsApp/Telegram). Bun não é recomendado.
    • Se a auth por token exigir um token e gateway.auth.token for gerenciado por SecretRef, a instalação do daemon o valida, mas não persiste valores de token em texto simples resolvidos nos metadados de ambiente do serviço supervisor.
    • Se a auth por token exigir um token e o SecretRef de token configurado não for resolvido, a instalação do daemon é bloqueada com orientação acionável.
    • Se tanto gateway.auth.token quanto gateway.auth.password estiverem configurados e gateway.auth.mode não estiver definido, a instalação do daemon é bloqueada até que o modo seja definido explicitamente.

  • Verificação de integridade

    • Inicia o Gateway (se necessário) e executa openclaw health.
    • Dica: openclaw status --deep adiciona a sonda de integridade do gateway ao vivo à saída de status, incluindo sondas de canal quando houver suporte (exige um gateway acessível).

  • Skills (recomendado)

    • Lê as skills disponíveis e verifica os requisitos.
    • Permite escolher um gerenciador de node: npm / pnpm (bun não recomendado).
    • Instala dependências opcionais (algumas usam Homebrew no macOS).

  • Finalizar

    • Resumo + próximos passos, incluindo o prompt Como você quer chocar seu agente? para Terminal, Browser ou mais tarde.

    • Modo não interativo

    Use --non-interactive para automatizar ou scriptar o onboarding:

    bash
    openclaw onboard --non-interactive \  --mode local \  --auth-choice apiKey \  --anthropic-api-key "$ANTHROPIC_API_KEY" \  --gateway-port 18789 \  --gateway-bind loopback \  --install-daemon \  --daemon-runtime node \  --skip-skills

    Adicione --json para um resumo legível por máquina.

    SecretRef de token do Gateway no modo não interativo:

    bash
    export OPENCLAW_GATEWAY_TOKEN="your-token"openclaw onboard --non-interactive \  --mode local \  --auth-choice skip \  --gateway-auth token \  --gateway-token-ref-env OPENCLAW_GATEWAY_TOKEN

    --gateway-token e --gateway-token-ref-env são mutuamente exclusivos.

    Exemplos de comandos específicos de provedor ficam em Automação da CLI. Use esta página de referência para a semântica de flags e a ordem das etapas.

    Adicionar agente (não interativo)

    bash
    openclaw agents add work \  --workspace ~/.openclaw/workspace-work \  --model openai/gpt-5.5 \  --bind whatsapp:biz \  --non-interactive \  --json

    RPC do assistente do Gateway

    O Gateway expõe o fluxo de onboarding por RPC (wizard.start, wizard.next, wizard.cancel, wizard.status). Clientes (app macOS, Control UI) podem renderizar etapas sem reimplementar a lógica de onboarding.

    Configuração do Signal (signal-cli)

    O onboarding pode instalar signal-cli a partir de releases do GitHub:

    • Baixa o asset de release apropriado.
    • Armazena-o em ~/.openclaw/tools/signal-cli/<version>/.
    • Grava channels.signal.cliPath na sua configuração.

    Observações:

    • Builds JVM exigem Java 21.
    • Builds nativos são usados quando disponíveis.
    • Windows usa WSL2; a instalação do signal-cli segue o fluxo Linux dentro do WSL.

    O que o assistente grava

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

    • agents.defaults.workspace
    • agents.defaults.model / models.providers (se Minimax for escolhido)
    • tools.profile (a integração inicial 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 (detalhes do comportamento: Referência de configuração da CLI)
    • 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ê optar por elas durante as solicitações (os nomes são resolvidos para IDs quando possível).
    • skills.install.nodeManager
      • setup --node-manager aceita npm, pnpm ou bun.
      • A configuração manual ainda pode usar yarn definindo skills.install.nodeManager diretamente.
    • 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/.

    Alguns canais são entregues como plugins. Quando você escolhe um durante a configuração, a integração inicial solicitará a instalação dele (npm ou um caminho local) antes que ele possa ser configurado.

    Documentos relacionados

    Was this useful?