Pular para o conteúdo principal

​
openclaw onboard

Onboarding interativo para configuração local ou remota do Gateway.

​
Guias relacionados

​
Exemplos

openclaw onboard
openclaw onboard --flow quickstart
openclaw onboard --flow manual
openclaw onboard --mode remote --remote-url wss://gateway-host:18789
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. 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-api-key é opcional no modo não interativo. Se omitido, o onboarding verifica CUSTOM_API_KEY. 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 tem como padrão http://127.0.0.1:11434. --custom-model-id é opcional; se omitido, o onboarding usa os padrões sugeridos pelo Ollama. IDs de modelo 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 ambiente em vez de valores de chave em texto simples. Para provedores com perfil de autenticação, isso grava entradas keyRef; para provedores personalizados, isso grava models.providers.<id>.apiKey como uma ref de ambiente (por exemplo { source: "env", provider: "default", id: "CUSTOM_API_KEY" }). Contrato do modo ref não interativo:
  • Defina a variável de ambiente 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 ambiente também esteja definida.
  • Se uma flag de chave inline for passada sem a variável de ambiente exigida, o onboarding falhará 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 ambiente.
  • --gateway-token e --gateway-token-ref-env são mutuamente exclusivos.
  • --gateway-token-ref-env exige uma variável de ambiente não vazia no ambiente do processo de onboarding.
  • Com --install-daemon, quando a autenticação por token exige um token, tokens de 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 puder ser resolvida, o onboarding falhará em modo fail-closed com orientação de correção.
  • Com --install-daemon, se gateway.auth.token e gateway.auth.password estiverem ambos 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 estiver sem gateway.mode, trate isso como dano na configuração ou uma edição manual incompleta, não como um atalho válido para modo local.
  • --allow-unconfigured é uma rota de escape separada do runtime do gateway. Isso não significa que o onboarding possa 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
Verificação de integridade do gateway local no modo não interativo:
  • A menos que você passe --skip-health, o onboarding espera um gateway local acessível antes de sair com sucesso.
  • --install-daemon inicia primeiro o caminho de instalação gerenciada do gateway. Sem ele, você já precisa ter um gateway local em execução, por exemplo openclaw gateway run.
  • Se você quiser apenas gravações de config/workspace/bootstrap na automação, use --skip-health.
  • No Windows nativo, --install-daemon tenta primeiro Tarefas Agendadas e recai para um item de login por usuário na pasta Inicializar se a criação da tarefa for negada.
Comportamento do onboarding interativo com modo de referência:
  • Escolha Use secret reference quando solicitado.
  • Depois escolha uma destas opções:
    • Variável de ambiente
    • Provedor de segredos configurado (file ou exec)
  • O onboarding faz uma validação rápida de preflight antes de salvar a ref.
    • Se a validação falhar, o onboarding mostra o erro e permite que você tente novamente.
Opções de endpoint Z.AI não interativas: Observação: --auth-choice zai-api-key agora detecta automaticamente o melhor endpoint Z.AI para sua chave (prefere a API geral com zai/glm-5). Se você quiser especificamente os endpoints do GLM Coding Plan, escolha zai-coding-global ou zai-coding-cn. 
# Seleção de endpoint sem prompt
openclaw onboard --non-interactive \
  --auth-choice zai-coding-global \
  --zai-api-key "$ZAI_API_KEY"

# Outras opções de endpoint Z.AI:
# --auth-choice zai-coding-cn
# --auth-choice zai-global
# --auth-choice zai-cn
Exemplo não interativo para Mistral: 
openclaw onboard --non-interactive \
  --auth-choice mistral-api-key \
  --mistral-api-key "$MISTRAL_API_KEY"
Observações sobre os fluxos:
  • quickstart: prompts mínimos, gera automaticamente um token do gateway.
  • manual: prompts completos para porta/bind/autenticação (alias de advanced).
  • Quando uma escolha de autenticação implica um provedor preferido, 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 preferido não retornar modelos carregados ainda, o onboarding recai para o catálogo sem filtro em vez de deixar o seletor vazio.
  • Na etapa de pesquisa na web, alguns provedores podem disparar prompts adicionais 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 solicitar 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 do escopo de DM no onboarding local: Referência de configuração da CLI.
  • O chat inicial 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 detecção automática.

​
Comandos comuns de acompanhamento

openclaw configure
openclaw agents add <name>
--json não implica modo não interativo. Use --non-interactive para scripts.