# openclaw onboard

로컬 또는 원격 Gateway 설정을 위한 대화형 온보딩입니다.

# 관련 가이드

# 예시

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는 Hermes 같은 Plugin 소유 마이그레이션 공급자를 사용합니다. 새 OpenClaw 설정에서만 실행됩니다. 기존 구성, 자격 증명, 세션 또는 워크스페이스 메모리/ID 파일이 있으면 가져오기 전에 재설정하거나 새 설정을 선택하세요.

--modern은 Crestodian 대화형 온보딩 미리 보기를 시작합니다. --modern이 없으면 openclaw onboard는 기존 온보딩 흐름을 유지합니다.

일반 텍스트 사설망 ws:// 대상의 경우(신뢰할 수 있는 네트워크만), 온보딩 프로세스 환경에서 OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1을 설정하세요. 이 클라이언트 측 전송 긴급 우회에는 대응되는 openclaw.json 설정이 없습니다.

비대화형 사용자 지정 공급자:

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는 비대화형 모드에서 선택 사항입니다. 생략하면 온보딩은 CUSTOM_API_KEY를 확인합니다. OpenClaw는 일반적인 비전 모델 ID를 이미지 지원 모델로 자동 표시합니다. 알 수 없는 사용자 지정 비전 ID에는 --custom-image-input을 전달하고, 텍스트 전용 메타데이터를 강제하려면 --custom-text-input을 전달하세요.

LM Studio는 비대화형 모드에서 공급자별 키 플래그도 지원합니다.

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:

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를 사용하면 온보딩은 일반 텍스트 키 값 대신 env 기반 참조를 기록합니다. 인증 프로필 기반 공급자의 경우 keyRef 항목을 기록하고, 사용자 지정 공급자의 경우 models.providers.<id>.apiKey를 env 참조로 기록합니다(예: { source: "env", provider: "default", id: "CUSTOM_API_KEY" }).

비대화형 ref 모드 계약:

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

비대화형 모드의 Gateway 토큰 옵션:

• --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로 관리되는 Gateway 토큰은 검증되지만 supervisor 서비스 환경 메타데이터에 해석된 일반 텍스트로 유지되지 않습니다.
• --install-daemon을 사용할 때 토큰 모드에 토큰이 필요하고 구성된 토큰 SecretRef가 해석되지 않으면, 온보딩은 복구 안내와 함께 닫힌 상태로 실패합니다.
• --install-daemon을 사용할 때 gateway.auth.token과 gateway.auth.password가 모두 구성되어 있고 gateway.auth.mode가 설정되지 않았다면, 모드가 명시적으로 설정될 때까지 온보딩은 설치를 차단합니다.
• 로컬 온보딩은 구성에 gateway.mode="local"을 기록합니다. 이후 구성 파일에 gateway.mode가 없다면, 이를 유효한 로컬 모드 단축 방식이 아니라 구성 손상 또는 불완전한 수동 편집으로 간주하세요.
• 로컬 온보딩은 선택한 설정 경로에 필요한 경우 선택된 다운로드 가능 Plugin을 설치합니다.
• 원격 온보딩은 원격 Gateway의 연결 정보만 기록하며 로컬 Plugin 패키지를 설치하지 않습니다.
• --allow-unconfigured는 별도의 Gateway 런타임 탈출구입니다. 이는 온보딩이 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

비대화형 로컬 Gateway 상태:

• --skip-health를 전달하지 않는 한, 온보딩은 연결 가능한 로컬 Gateway를 기다린 뒤 성공적으로 종료합니다.
• --install-daemon은 먼저 관리형 Gateway 설치 경로를 시작합니다. 이 옵션이 없으면 예를 들어 openclaw gateway run처럼 로컬 Gateway가 이미 실행 중이어야 합니다.
• 자동화에서 구성/워크스페이스/부트스트랩 기록만 원한다면 --skip-health를 사용하세요.
• 워크스페이스 파일을 직접 관리한다면 --skip-bootstrap을 전달하여 agents.defaults.skipBootstrap: true를 설정하고 AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md, HEARTBEAT.md, BOOTSTRAP.md 생성을 건너뛰세요.
• 네이티브 Windows에서는 --install-daemon이 먼저 Scheduled Tasks를 시도하고, 작업 생성이 거부되면 사용자별 Startup 폴더 로그인 항목으로 폴백합니다.

참조 모드의 대화형 온보딩 동작:

• 프롬프트가 표시되면 비밀 참조 사용을 선택합니다.
• 그런 다음 다음 중 하나를 선택합니다.
  • 환경 변수
  • 구성된 비밀 공급자(file 또는 exec)
• 온보딩은 참조를 저장하기 전에 빠른 사전 검증을 수행합니다.
  • 검증에 실패하면 온보딩은 오류를 표시하고 다시 시도할 수 있게 합니다.

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

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

# 흐름 참고 사항

# 일반적인 후속 명령

openclaw configure
openclaw agents add <name>