​

openclaw onboard

​

관련 가이드

• CLI 온보딩 허브: 온보딩(CLI)
• 온보딩 개요: 온보딩 개요
• CLI 온보딩 참조: CLI 설정 참조
• CLI 자동화: CLI 자동화
• macOS 온보딩: 온보딩(macOS 앱)

​

예시

openclaw onboard
openclaw onboard --flow quickstart
openclaw onboard --flow manual
openclaw onboard --mode remote --remote-url wss://gateway-host:18789

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

openclaw onboard --non-interactive \
  --auth-choice ollama \
  --custom-base-url "http://ollama-host:11434" \
  --custom-model-id "qwen3.5:27b" \
  --accept-risk

openclaw onboard --non-interactive \
  --auth-choice openai-api-key \
  --secret-input-mode ref \
  --accept-risk

• 온보딩 프로세스 환경에서 provider env var를 설정하세요(예: OPENAI_API_KEY).
• 해당 env var도 설정되어 있지 않다면 인라인 키 플래그(예: --openai-api-key)를 전달하지 마세요.
• 필요한 env var 없이 인라인 키 플래그가 전달되면, 온보딩은 안내 메시지와 함께 즉시 실패합니다.

• --gateway-auth token --gateway-token <token>은 일반 텍스트 토큰을 저장합니다.
• --gateway-auth token --gateway-token-ref-env <name>은 gateway.auth.token을 env SecretRef로 저장합니다.
• --gateway-token과 --gateway-token-ref-env는 서로 함께 사용할 수 없습니다.
• --gateway-token-ref-env는 온보딩 프로세스 환경에 비어 있지 않은 env var가 필요합니다.
• --install-daemon 사용 시 토큰 인증에 토큰이 필요한 경우, SecretRef로 관리되는 게이트웨이 토큰은 검증되지만 supervisor 서비스 환경 메타데이터에 해석된 일반 텍스트로 저장되지는 않습니다.
• --install-daemon 사용 시 토큰 모드에 토큰이 필요하고 구성된 토큰 SecretRef가 해석되지 않으면, 온보딩은 해결 방법 안내와 함께 실패 종료합니다.
• --install-daemon 사용 시 gateway.auth.token과 gateway.auth.password가 모두 구성되어 있는데 gateway.auth.mode가 설정되지 않은 경우, 온보딩은 모드를 명시적으로 설정할 때까지 설치를 차단합니다.
• 로컬 온보딩은 config에 gateway.mode="local"을 기록합니다. 이후 config 파일에 gateway.mode가 없다면, 이는 유효한 로컬 모드 단축 경로가 아니라 config 손상 또는 불완전한 수동 편집으로 간주해야 합니다.
• --allow-unconfigured는 별도의 게이트웨이 런타임 이스케이프 해치입니다. 온보딩에서 gateway.mode를 생략해도 된다는 뜻은 아닙니다.

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

• --skip-health를 전달하지 않으면, 온보딩은 도달 가능한 로컬 게이트웨이를 확인한 뒤에만 성공적으로 종료합니다.
• --install-daemon은 먼저 관리형 게이트웨이 설치 경로를 시작합니다. 이를 사용하지 않으면 openclaw gateway run처럼 로컬 게이트웨이가 이미 실행 중이어야 합니다.
• 자동화에서 config/workspace/bootstrap 기록만 원한다면 --skip-health를 사용하세요.
• 네이티브 Windows에서 --install-daemon은 먼저 Scheduled Tasks를 시도하고, 작업 생성이 거부되면 사용자별 Startup 폴더 로그인 항목으로 대체합니다.

• 프롬프트가 나타나면 Use secret reference를 선택하세요.
• 그다음 다음 중 하나를 선택하세요:
  • 환경 변수
  • 구성된 secret provider(file 또는 exec)
• 온보딩은 ref를 저장하기 전에 빠른 사전 검증을 수행합니다.
  • 검증에 실패하면, 온보딩은 오류를 표시하고 다시 시도할 수 있게 합니다.

# 프롬프트 없는 엔드포인트 선택
openclaw onboard --non-interactive \
  --auth-choice zai-coding-global \
  --zai-api-key "$ZAI_API_KEY"

# 다른 Z.AI 엔드포인트 선택:
# --auth-choice zai-coding-cn
# --auth-choice zai-global
# --auth-choice zai-cn

openclaw onboard --non-interactive \
  --auth-choice mistral-api-key \
  --mistral-api-key "$MISTRAL_API_KEY"

• quickstart: 최소 프롬프트, 게이트웨이 토큰 자동 생성.
• manual: 포트/바인드/인증에 대한 전체 프롬프트(advanced의 별칭).
• 인증 선택이 선호 provider를 암시하는 경우, 온보딩은 기본 모델 및 허용 목록 선택기를 해당 provider로 미리 필터링합니다. Volcengine과 BytePlus의 경우 coding-plan 변형도 함께 일치시킵니다 (volcengine-plan/*, byteplus-plan/*).
• 선호 provider 필터에서 아직 로드된 모델이 하나도 없으면, 온보딩은 선택기를 비워 두는 대신 필터링되지 않은 카탈로그로 대체합니다.
• 웹 검색 단계에서 일부 provider는 provider별 후속 프롬프트를 트리거할 수 있습니다:
  • Grok은 동일한 XAI_API_KEY와 x_search 모델 선택으로 선택적 x_search 설정을 제안할 수 있습니다.
  • Kimi는 Moonshot API 리전(api.moonshot.ai vs api.moonshot.cn)과 기본 Kimi 웹 검색 모델을 물을 수 있습니다.
• 로컬 온보딩 DM 범위 동작: CLI 설정 참조.
• 가장 빠른 첫 채팅: openclaw dashboard(제어 UI, 채널 설정 불필요).
• 사용자 지정 Provider: 목록에 없는 호스팅 provider를 포함해 OpenAI 또는 Anthropic 호환 엔드포인트에 연결합니다. 자동 감지에는 Unknown을 사용하세요.

​

일반적인 후속 명령

openclaw configure
openclaw agents add <name>