openclaw onboard

대화형 온보딩 마법사 (로컬 또는 원격 게이트웨이 설정).

관련 가이드

사용 예시

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

신뢰할 수 있는 네트워크에서만 사용하는 일반 텍스트 사설 네트워크 ws:// 대상의 경우, 온보딩 프로세스 환경에서 OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1을 설정하세요.

비대화형 커스텀 프로바이더:

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는 비대화형 모드에서 선택 사항입니다. 생략 시 온보딩이 CUSTOM_API_KEY를 확인합니다.

비대화형 Ollama:

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의 기본값은 http://127.0.0.1:11434입니다. --custom-model-id는 선택 사항이며, 생략 시 Ollama의 권장 기본값을 사용합니다. kimi-k2.5:cloud와 같은 클라우드 모델 ID도 사용할 수 있습니다.

프로바이더 키를 평문 대신 참조로 저장:

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

--secret-input-mode ref를 사용하면 온보딩이 평문 키 값 대신 환경변수 기반 참조를 기록합니다. 인증 프로필 기반 프로바이더는 keyRef 항목을 기록하고, 커스텀 프로바이더는 models.providers.<id>.apiKey를 환경변수 참조로 기록합니다 (예: { source: "env", provider: "default", id: "CUSTOM_API_KEY" }).

비대화형 ref 모드 규약:

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

비대화형 모드에서의 게이트웨이 토큰 옵션:

  • --gateway-auth token --gateway-token <token>은 평문 토큰을 저장합니다.
  • --gateway-auth token --gateway-token-ref-env <name>은 gateway.auth.token을 환경변수 SecretRef로 저장합니다.
  • --gateway-token과 --gateway-token-ref-env는 상호 배타적입니다.
  • --gateway-token-ref-env는 온보딩 프로세스 환경에 비어 있지 않은 환경 변수가 필요합니다.
  • --install-daemon과 함께 사용 시, 토큰 인증에 토큰이 필요한 경우 SecretRef로 관리되는 게이트웨이 토큰은 검증되지만 수퍼바이저 서비스 환경 메타데이터에 확인된 평문으로 저장되지 않습니다.
  • --install-daemon과 함께 사용 시, 토큰 모드에 토큰이 필요하고 구성된 토큰 SecretRef가 확인되지 않으면, 수정 안내와 함께 온보딩이 안전하게 실패합니다.
  • --install-daemon과 함께 사용 시, gateway.auth.token과 gateway.auth.password가 모두 구성되어 있고 gateway.auth.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).
  • 자동화에서 설정/작업 공간/부트스트랩 쓰기만 필요한 경우 --skip-health를 사용하세요.
  • 네이티브 Windows에서 --install-daemon은 먼저 예약된 작업을 시도하고, 작업 생성이 거부되면 사용자별 시작 폴더 로그인 항목으로 대체합니다.

참조 모드를 사용한 대화형 온보딩 동작:

  • 프롬프트에서 시크릿 참조 사용을 선택합니다.
  • 그런 다음 다음 중 하나를 선택합니다:
    • 환경 변수
    • 구성된 시크릿 프로바이더 (file 또는 exec)
  • 온보딩은 참조를 저장하기 전에 빠른 사전 검증을 수행합니다.
    • 검증에 실패하면 오류를 표시하고 재시도할 수 있습니다.

비대화형 Z.AI 엔드포인트 선택:

참고: --auth-choice zai-api-key는 이제 키에 가장 적합한 Z.AI 엔드포인트를 자동 감지합니다 (zai/glm-5를 사용하는 일반 API 우선). GLM Coding Plan 엔드포인트를 명시적으로 원하는 경우 zai-coding-global 또는 zai-coding-cn을 선택하세요.

# 프롬프트 없는 엔드포인트 선택
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

비대화형 Mistral 예시:

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

플로우 참고:

  • quickstart: 최소한의 프롬프트, 게이트웨이 토큰 자동 생성.
  • manual: 포트/바인드/인증에 대한 전체 프롬프트 (advanced의 별칭).
  • 로컬 온보딩 DM 범위 동작: CLI Onboarding Reference.
  • 가장 빠른 첫 대화: openclaw dashboard (Control UI, 채널 설정 불필요).
  • 커스텀 프로바이더: 목록에 없는 호스팅 프로바이더를 포함하여 OpenAI 또는 Anthropic 호환 엔드포인트에 연결. Unknown을 사용하여 자동 감지.

일반적인 후속 명령어

openclaw configure
openclaw agents add <name>

참고: --json은 비대화형 모드를 의미하지 않습니다. 스크립트에서는 --non-interactive를 사용하세요.

arrow_back
이전
Nodes
다음
Pairing
arrow_forward