온보딩 마법사 (CLI)

온보딩 마법사는 macOS, Linux, Windows(WSL2 강력 권장)에서 OpenClaw를 설정하는 권장 방법입니다. 로컬 Gateway 또는 원격 Gateway 연결을 구성하고, 채널, 스킬, 워크스페이스 기본값을 하나의 안내 흐름으로 설정합니다.

openclaw onboard

참고: 가장 빠른 첫 대화: Control UI를 열면 채널 설정 없이 바로 사용할 수 있습니다. openclaw dashboard를 실행하고 브라우저에서 채팅하세요. 문서: 대시보드.

나중에 재설정하려면:

openclaw configure
openclaw agents add <name>

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

팁: 온보딩 마법사에는 웹 검색 단계가 포함되어 있어 프로바이더(Perplexity, Brave, Gemini, Grok, Kimi)를 선택하고 API 키를 입력하면 에이전트가 web_search를 사용할 수 있습니다. 나중에 openclaw configure --section web으로도 설정할 수 있습니다. 문서: 웹 도구.

QuickStart vs Advanced

마법사를 시작하면 QuickStart (기본값)와 Advanced (전체 제어) 중 선택할 수 있습니다.

QuickStart (기본값)

- 로컬 Gateway (루프백)
- 기본 워크스페이스 (또는 기존 워크스페이스)
- Gateway 포트 **18789**
- Gateway 인증 **Token** (루프백에서도 자동 생성)
- 새 로컬 설정의 기본 도구 정책: `tools.profile: "coding"` (기존에 명시적으로 설정된 프로필은 유지)
- DM 격리 기본값: 로컬 온보딩 시 `session.dmScope: "per-channel-peer"`가 미설정이면 자동으로 작성됩니다. 상세: [CLI 온보딩 레퍼런스](/docs/start/wizard-cli-reference#outputs-and-internals)
- Tailscale 노출 **Off**
- Telegram + WhatsApp DM 기본값은 **허용 목록** (전화번호 입력 요청)

Advanced (전체 제어)

- 모든 단계를 노출합니다(모드, 워크스페이스, Gateway, 채널, 데몬, 스킬).

마법사가 설정하는 항목

**로컬 모드 (기본)**에서는 다음 단계를 안내합니다:

모델/인증 — 지원되는 모든 프로바이더/인증 흐름(API 키, OAuth, setup-token)을 선택할 수 있으며, Custom Provider(OpenAI 호환, Anthropic 호환, Unknown 자동 감지)도 지원합니다. 기본 모델을 선택하세요. 보안 참고: 이 에이전트가 도구를 실행하거나 웹훅/훅 콘텐츠를 처리할 예정이라면 가장 강력한 최신 세대 모델을 사용하고 도구 정책을 엄격하게 유지하세요. 약한/오래된 모델은 프롬프트 인젝션에 취약합니다. 비대화형 실행 시 --secret-input-mode ref는 API 키 값 대신 환경 변수 기반 참조를 인증 프로필에 저장합니다. 비대화형 ref 모드에서는 프로바이더 환경 변수가 설정되어 있어야 합니다. 해당 환경 변수 없이 인라인 키 플래그를 전달하면 즉시 실패합니다. 대화형 실행에서 시크릿 참조 모드를 선택하면 환경 변수 또는 설정된 프로바이더 참조(file 또는 exec)를 가리킬 수 있으며, 저장 전 빠른 사전 검증이 실행됩니다.
워크스페이스 — 에이전트 파일 위치(기본: ~/.openclaw/workspace). 부트스트랩 파일을 생성합니다.
Gateway — 포트, 바인드 주소, 인증 모드, Tailscale 노출. 대화형 토큰 모드에서는 기본 평문 토큰 저장 또는 SecretRef 옵트인을 선택할 수 있습니다. 비대화형 토큰 SecretRef 경로: --gateway-token-ref-env <ENV_VAR>.
채널 — WhatsApp, Telegram, Discord, Google Chat, Mattermost, Signal, BlueBubbles, iMessage.
데몬 — LaunchAgent(macOS) 또는 systemd 사용자 유닛(Linux/WSL2)을 설치합니다. 토큰 인증이 토큰을 필요로 하고 gateway.auth.token이 SecretRef로 관리되는 경우, 데몬 설치는 이를 검증하지만 해결된 토큰을 슈퍼바이저 서비스 환경 메타데이터에 저장하지는 않습니다. 토큰 인증이 토큰을 필요로 하고 설정된 토큰 SecretRef가 해결되지 않으면 실행 가능한 안내와 함께 데몬 설치가 차단됩니다. gateway.auth.token과 gateway.auth.password가 모두 설정되어 있고 gateway.auth.mode가 미설정이면 모드가 명시적으로 설정될 때까지 데몬 설치가 차단됩니다.
헬스 체크 — Gateway를 시작하고 실행 상태를 확인합니다.
스킬 — 권장 스킬과 선택적 종속성을 설치합니다.

참고: 마법사를 다시 실행해도 명시적으로 Reset을 선택하거나 --reset을 전달하지 않는 한 기존 설정을 지우지 않습니다. CLI --reset은 기본적으로 설정, 인증 정보, 세션을 대상으로 합니다. --reset-scope full을 사용하면 워크스페이스도 포함됩니다. 설정이 유효하지 않거나 레거시 키를 포함하고 있으면 마법사가 먼저 openclaw doctor를 실행하도록 안내합니다.

원격 모드는 이 머신에서 다른 곳에 있는 Gateway에 연결하도록 로컬 클라이언트만 설정합니다. 원격 호스트에는 아무것도 설치하거나 변경하지 않습니다.

에이전트 추가

openclaw agents add <name>으로 별도의 워크스페이스, 세션, 인증 프로필을 가진 에이전트를 추가할 수 있습니다. --workspace 없이 실행하면 마법사가 시작됩니다.

설정되는 항목:

agents.list[].name
agents.list[].workspace
agents.list[].agentDir

참고:

기본 워크스페이스는 ~/.openclaw/workspace-<agentId> 형식을 따릅니다.
bindings를 추가하여 인바운드 메시지를 라우팅할 수 있습니다(마법사로도 가능).
비대화형 플래그: --model, --agent-dir, --bind, --non-interactive.

전체 레퍼런스

단계별 상세 분석과 설정 출력에 대해서는 CLI 온보딩 레퍼런스를 참고하세요. 비대화형 예제는 CLI 자동화를 참고하세요. RPC 상세를 포함한 심화 기술 레퍼런스는 마법사 레퍼런스를 참고하세요.