Pular para o conteúdo principal

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
openclaw onboard

Onboarding guiado completo para configuração de Gateway local ou remoto. Use isto quando quiser que o OpenClaw conduza autenticação de modelos, workspace, gateway, canais, Skills e integridade em um único fluxo.

​
Guias relacionados

Central de onboarding da CLI

Passo a passo do fluxo interativo da CLI.

Visão geral do onboarding

Como o onboarding do OpenClaw se integra.

Referência de configuração da CLI

Saídas, detalhes internos e comportamento por etapa.

Automação da CLI

Flags não interativas e configurações por script.

Onboarding do app macOS

Fluxo de onboarding para o app da barra de menus do macOS.

​
Exemplos

openclaw onboard
openclaw onboard --modern
openclaw onboard --flow quickstart
openclaw onboard --flow manual
openclaw onboard --flow import
openclaw onboard --import-from hermes --import-source ~/.hermes
openclaw onboard --skip-bootstrap
openclaw onboard --mode remote --remote-url wss://gateway-host:18789
--flow import usa provedores de migração pertencentes a plugins, como Hermes. Ele só é executado em uma configuração nova do OpenClaw; se já houver configuração, credenciais, sessões ou arquivos de memória/identidade do workspace, redefina ou escolha uma configuração nova antes de importar. --modern inicia a prévia de onboarding conversacional do Crestodian. Sem --modern, openclaw onboard mantém o fluxo clássico de onboarding. Para destinos ws:// em texto simples em rede privada (somente redes confiáveis), defina OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1 no ambiente do processo de onboarding. Não há equivalente em openclaw.json para este break-glass de transporte do lado do cliente. Provedor personalizado não interativo: 
openclaw onboard --non-interactive \
  --auth-choice custom-api-key \
  --custom-base-url "https://llm.example.com/v1" \
  --custom-model-id "foo-large" \
  --custom-api-key "$CUSTOM_API_KEY" \
  --secret-input-mode plaintext \
  --custom-compatibility openai \
  --custom-image-input
--custom-api-key é opcional no modo não interativo. Se omitido, o onboarding verifica CUSTOM_API_KEY. O OpenClaw marca automaticamente IDs comuns de modelos de visão como compatíveis com imagem. Passe --custom-image-input para IDs personalizados de visão desconhecidos, ou --custom-text-input para forçar metadados somente de texto. O LM Studio também aceita uma flag de chave específica do provedor no modo não interativo: 
openclaw onboard --non-interactive \
  --auth-choice lmstudio \
  --custom-base-url "http://localhost:1234/v1" \
  --custom-model-id "qwen/qwen3.5-9b" \
  --lmstudio-api-key "$LM_API_TOKEN" \
  --accept-risk
Ollama não interativo: 
openclaw onboard --non-interactive \
  --auth-choice ollama \
  --custom-base-url "http://ollama-host:11434" \
  --custom-model-id "qwen3.5:27b" \
  --accept-risk
--custom-base-url usa http://127.0.0.1:11434 por padrão. --custom-model-id é opcional; se omitido, o onboarding usa os padrões sugeridos pelo Ollama. IDs de modelos em nuvem, como kimi-k2.5:cloud, também funcionam aqui. Armazene chaves de provedor como refs em vez de texto simples: 
openclaw onboard --non-interactive \
  --auth-choice openai-api-key \
  --secret-input-mode ref \
  --accept-risk
Com --secret-input-mode ref, o onboarding grava refs baseadas em env em vez de valores de chave em texto simples. Para provedores baseados em perfil de autenticação, isso grava entradas keyRef; para provedores personalizados, isso grava models.providers.<id>.apiKey como uma ref de env (por exemplo, { source: "env", provider: "default", id: "CUSTOM_API_KEY" }). Contrato do modo não interativo ref:
  • Defina a variável de env do provedor no ambiente do processo de onboarding (por exemplo, OPENAI_API_KEY).
  • Não passe flags de chave inline (por exemplo, --openai-api-key) a menos que essa variável de env também esteja definida.
  • Se uma flag de chave inline for passada sem a variável de env necessária, o onboarding falha rapidamente com orientação.
Opções de token do Gateway no modo não interativo:
  • --gateway-auth token --gateway-token <token> armazena um token em texto simples.
  • --gateway-auth token --gateway-token-ref-env <name> armazena gateway.auth.token como uma SecretRef de env.
  • --gateway-token e --gateway-token-ref-env são mutuamente exclusivos.
  • --gateway-token-ref-env exige uma variável de env não vazia no ambiente do processo de onboarding.
  • Com --install-daemon, quando a autenticação por token exige um token, tokens do gateway gerenciados por SecretRef são validados, mas não persistidos como texto simples resolvido nos metadados de ambiente do serviço supervisor.
  • Com --install-daemon, se o modo de token exigir um token e a SecretRef de token configurada não for resolvida, o onboarding falha fechado com orientação de correção.
  • Com --install-daemon, se tanto gateway.auth.token quanto gateway.auth.password estiverem configurados e gateway.auth.mode não estiver definido, o onboarding bloqueia a instalação até que o modo seja definido explicitamente.
  • O onboarding local grava gateway.mode="local" na configuração. Se um arquivo de configuração posterior não tiver gateway.mode, trate isso como dano de configuração ou edição manual incompleta, não como um atalho válido de modo local.
  • O onboarding local instala os plugins baixáveis selecionados quando o caminho de configuração escolhido exige isso.
  • O onboarding remoto grava apenas informações de conexão para o Gateway remoto e não instala pacotes de plugins locais.
  • --allow-unconfigured é uma saída de emergência separada do runtime do gateway. Ela não significa que o onboarding pode omitir gateway.mode.
Exemplo: 
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 \
  --accept-risk
Integridade do gateway local não interativo:
  • A menos que você passe --skip-health, o onboarding aguarda um gateway local acessível antes de sair com sucesso.
  • --install-daemon inicia primeiro o caminho de instalação do gateway gerenciado. Sem ele, você já deve ter um gateway local em execução, por exemplo openclaw gateway run.
  • Se você só quiser gravações de configuração/workspace/bootstrap em automação, use --skip-health.
  • Se você gerencia os arquivos do workspace por conta própria, passe --skip-bootstrap para definir agents.defaults.skipBootstrap: true e pular a criação de AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md, HEARTBEAT.md e BOOTSTRAP.md.
  • No Windows nativo, --install-daemon tenta primeiro Tarefas Agendadas e recorre a um item de login na pasta Inicializar por usuário se a criação da tarefa for negada.
Comportamento do onboarding interativo com modo de referência:
  • Escolha Usar referência de segredo quando solicitado.
  • Em seguida, escolha uma das opções:
    • Variável de ambiente
    • Provedor de segredo configurado (file ou exec)
  • O onboarding executa uma validação rápida de preflight antes de salvar a ref.
    • Se a validação falhar, o onboarding mostra o erro e permite tentar novamente.

​
Escolhas de endpoint Z.AI não interativas

--auth-choice zai-api-key detecta automaticamente o melhor endpoint Z.AI para sua chave (prefere a API geral com zai/glm-5.1). Se você quiser especificamente os endpoints GLM Coding Plan, escolha zai-coding-global ou zai-coding-cn.
# Promptless endpoint selection
openclaw onboard --non-interactive \
  --auth-choice zai-coding-global \
  --zai-api-key "$ZAI_API_KEY"

# Other Z.AI endpoint choices:
# --auth-choice zai-coding-cn
# --auth-choice zai-global
# --auth-choice zai-cn
Exemplo não interativo do Mistral: 
openclaw onboard --non-interactive \
  --auth-choice mistral-api-key \
  --mistral-api-key "$MISTRAL_API_KEY"

​
Observações sobre o fluxo

  • quickstart: prompts mínimos, gera automaticamente um token de gateway.
  • manual: prompts completos para porta, bind e autenticação (alias de advanced).
  • import: executa um provedor de migração detectado, pré-visualiza o plano e aplica após confirmação.
Quando uma escolha de autenticação implica um provedor preferencial, o onboarding pré-filtra os seletores de modelo padrão e allowlist para esse provedor. Para Volcengine e BytePlus, isso também corresponde às variantes de plano de codificação (volcengine-plan/*, byteplus-plan/*).Se o filtro de provedor preferencial ainda não produzir modelos carregados, o onboarding recorre ao catálogo não filtrado em vez de deixar o seletor vazio.
Alguns provedores de pesquisa na web acionam prompts de acompanhamento específicos do provedor:
  • Grok pode oferecer configuração opcional de x_search com a mesma XAI_API_KEY e uma escolha de modelo x_search.
  • Kimi pode perguntar a região da API Moonshot (api.moonshot.ai vs api.moonshot.cn) e o modelo padrão de pesquisa na web do Kimi.
  • Comportamento de escopo de DM no onboarding local: Referência de configuração da CLI.
  • Primeiro chat mais rápido: openclaw dashboard (UI de controle, sem configuração de canal).
  • Provedor personalizado: conecte qualquer endpoint compatível com OpenAI ou Anthropic, incluindo provedores hospedados não listados. Use Unknown para detectar automaticamente.
  • Se o estado do Hermes for detectado, o onboarding oferece um fluxo de migração. Use Migrar para planos dry-run, modo de substituição, relatórios e mapeamentos exatos.

​
Comandos comuns de acompanhamento

openclaw channels add
openclaw configure
openclaw agents add <name>
Use openclaw setup em vez disso quando você só precisar da configuração/workspace de base. Use openclaw configure depois para mudanças direcionadas e openclaw channels add para configuração apenas de canais.
--json não implica modo não interativo. Use --non-interactive para scripts.