메인 콘텐츠로 건너뛰기

​
openclaw onboard

interactive onboarding wizard입니다. (local 또는 remote Gateway setup)

​
Examples

신뢰할 수 있는 private network에서만 ws:// target을 써야 한다면, onboarding process environment에 OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1을 설정하세요. Non-interactive custom provider:
non-interactive mode에서 --custom-api-key는 선택 사항입니다. 생략하면 onboarding은 CUSTOM_API_KEY를 확인합니다. plaintext 대신 provider key를 ref로 저장:
--secret-input-mode ref를 쓰면 onboarding은 plaintext key 값 대신 env-backed ref를 기록합니다. auth-profile backed provider는 keyRef entry를 쓰고, custom provider는 models.providers.<id>.apiKey를 env ref로 기록합니다. (예: { source: "env", provider: "default", id: "CUSTOM_API_KEY" }) Non-interactive ref mode contract:
  • provider env var를 onboarding process environment에 설정하세요. (예: OPENAI_API_KEY)
  • inline key flag(예: --openai-api-key)는 해당 env var도 함께 설정된 경우에만 전달하세요.
  • 필요한 env var 없이 inline key flag를 넘기면 onboarding은 안내와 함께 즉시 실패합니다.
non-interactive mode의 Gateway token option:
  • --gateway-auth token --gateway-token <token>은 plaintext token을 저장합니다.
  • --gateway-auth token --gateway-token-ref-env <name>은 gateway.auth.token을 env SecretRef로 저장합니다.
  • --gateway-token과 --gateway-token-ref-env는 함께 사용할 수 없습니다.
  • --gateway-token-ref-env는 onboarding process environment에 비어 있지 않은 env var가 필요합니다.
  • --install-daemon과 함께 쓸 때 token auth가 token을 요구하면, SecretRef-managed gateway token은 검증되지만 supervisor service environment metadata에 resolved plaintext로 저장되지는 않습니다.
  • --install-daemon과 함께 쓸 때 token mode가 token을 요구하고 configured token SecretRef가 unresolved 상태면, onboarding은 remediation guidance와 함께 fail-closed로 동작합니다.
  • --install-daemon과 함께 쓸 때 gateway.auth.token과 gateway.auth.password가 모두 configured되어 있고 gateway.auth.mode가 비어 있으면, mode를 명시하기 전까지 install이 차단됩니다.
Example:
interactive onboarding에서 reference mode를 사용할 때:
  • prompt에서 Use secret reference를 선택합니다.
  • 다음 중 하나를 선택합니다.
    • Environment variable
    • Configured secret provider (file 또는 exec)
  • onboarding은 저장 전에 빠른 preflight validation을 수행합니다.
    • validation이 실패하면 오류를 보여 주고 다시 시도할 수 있게 합니다.
Non-interactive Z.AI endpoint choice: 참고: --auth-choice zai-api-key는 이제 key에 가장 맞는 Z.AI endpoint를 자동 감지합니다. (zai/glm-5가 있는 general API 선호) GLM Coding Plan endpoint를 명시적으로 원하면 zai-coding-global 또는 zai-coding-cn을 선택하세요.
Non-interactive Mistral example:
Flow notes:
  • quickstart: 최소 질문만 묻고, gateway token을 자동 생성합니다.
  • manual: port/bind/auth 전체 질문을 보여 줍니다. (advanced의 alias)
  • local onboarding DM scope behavior: CLI Onboarding Reference
  • 가장 빠른 첫 chat: openclaw dashboard (Control UI, channel setup 불필요)
  • Custom Provider: 목록에 없는 OpenAI 또는 Anthropic compatible endpoint를 연결할 수 있습니다. Unknown을 선택하면 auto-detect를 시도합니다.

​
Common follow-up commands

--json은 non-interactive mode를 의미하지 않습니다. script에서는 --non-interactive를 사용하세요.