openclaw onboard 완벽 가이드: 한 번에 끝내는 초기 설정

새로운 개발 도구를 설치하고 초기 설정을 마치는 과정은 늘 번거롭습니다. API 키를 찾고, 설정 파일을 만들고, 환경 변수를 맞추다 보면 정작 중요한 작업은 시작하기도 전에 지치곤 하죠. 설정 과정에서 하나라도 놓치면 원인을 알 수 없는 에러를 마주하게 되어 답답할 때가 많습니다.

이런 번거로움을 줄이기 위해 openclaw onboard 명령어가 준비되어 있습니다. 복잡한 과정을 단계별로 안내해 주는 마법사(Wizard)를 통해 로컬 환경이나 원격 서버 연결을 쉽고 빠르게 마칠 수 있습니다.

필요한 것

시작하기 전에 다음 항목들이 준비되었는지 확인해 주세요. (소스 문서 기준)

openclaw CLI 설치
API Key 또는 구독 정보 (Anthropic, OpenAI, xAI, OpenCode 등 중 선택)
Node.js (WhatsApp 및 Telegram 채널 사용 시 필수)
Java 21 (Signal JVM 빌드 사용 시 필요)
pnpm 또는 npm (Skills 설치용)

빠른 시작

가장 빠른 설정 경로는 로컬 모드(Local mode)를 사용하는 것입니다. 터미널에서 다음 명령어를 입력하세요.

openclaw onboard

마법사가 시작되면 다음 단계들을 거치게 됩니다.

기존 설정 감지: ~/.openclaw/openclaw.json 파일이 있다면 유지(Keep), 수정(Modify), 초기화(Reset) 중 선택합니다.
Model 및 Auth 설정: Anthropic API key, OpenAI Code subscription(OAuth) 등 원하는 모델과 인증 방식을 선택합니다.
Workspace 설정: 기본 경로는 ~/.openclaw/workspace이며, 첫 실행에 필요한 파일들이 생성됩니다.
Gateway 설정: Port, Bind 주소, 인증 모드를 설정합니다. 로컬에서만 쓰더라도 Token 인증을 켜두는 것이 안전합니다.
Channels 설정: Telegram, Discord, WhatsApp 등 연결할 메시징 채널의 토큰이나 JSON 파일을 입력합니다.
Daemon 설치: macOS는 LaunchAgent, Linux/WSL2는 systemd를 통해 백그라운드 실행을 설정합니다.
Health check: Gateway를 실행하고 openclaw health를 통해 정상 작동 여부를 확인합니다.
Skills 설정: npm 또는 pnpm을 선택해 필요한 도구와 의존성을 설치합니다.

만약 다른 곳에 실행 중인 Gateway에 연결하고 싶다면 Remote mode를 선택하세요. 원격 Gateway의 URL과 Token만 입력하면 이 장치에서 바로 연결할 수 있습니다.

주요 인증 옵션

Anthropic API key: 키를 직접 입력하거나 ANTHROPIC_API_KEY 환경 변수를 사용합니다.
Anthropic OAuth: macOS Keychain이나 기존 Claude Code CLI의 자격 증명을 재사용합니다.
OpenAI Code subscription: 브라우저를 통해 OAuth 로그인을 진행합니다.
OpenAI API key: 키를 입력하면 ~/.openclaw/.env에 저장되어 Daemon이 읽을 수 있게 됩니다.

문제 해결

설정 중 문제가 발생하면 다음 해결 방법을 참고하세요.

설정 파일 오류: 기존 설정이 유효하지 않거나 오래된 키가 포함되어 있다면 마법사가 중단됩니다. 이 경우 openclaw doctor를 실행해 문제를 진단하세요.
GUI를 감지할 수 없는 경우: 브라우저를 열 수 없는 환경이라면 마법사가 Control UI 접속을 위한 SSH 포트 포워딩 안내를 출력합니다.
UI 에셋 누락: Control UI 에셋이 없다면 마법사가 직접 빌드를 시도합니다. 수동으로 빌드하려면 pnpm ui:build를 실행하세요.
Signal 설치 문제: Windows 사용자는 WSL2를 통해 Linux용 signal-cli 흐름을 따라야 합니다.

더 궁금한 점이 있다면 AI Setup Assistant에게 물어보세요.

다음 단계

OpenClaw Expert

아직 막혀 있나요?

이 문서에서 답을 못 찾았다면 OpenClaw Expert에게 바로 물어보세요.