OpenClaw CLI Onboarding 가이드: 5분 만에 에이전트 설정하기

새로운 개발 도구를 도입할 때 가장 번거로운 순간은 언제일까요? 아마 수많은 설정 파일과 API 키, 복잡한 환경 변수를 하나하나 맞추는 과정일 거예요. 설정을 마치기도 전에 진이 빠지는 경험, 개발자라면 누구나 한 번쯤 있죠. OpenClaw는 이런 번거로움을 줄이기 위해 모든 과정을 한 번에 해결해 주는 Onboarding Wizard를 제공해요.

필요한 것

시작하기 전에 다음 환경 중 하나를 사용하고 있는지 확인해 주세요.

• macOS
• Linux
• Windows (WSL2 환경 권장)

빠른 시작

가장 권장하는 설정 방법은 CLI에서 Onboarding Wizard를 실행하는 거예요. 이 가이드를 따라가면 Gateway, Channel, Skill, Workspace 기본값까지 한 번에 설정할 수 있어요.

openclaw onboard

만약 설정을 건너뛰고 바로 채팅을 시작하고 싶다면 Control UI를 사용해 보세요. 브라우저에서 바로 대화가 가능해요.

openclaw dashboard

나중에 설정을 변경하거나 새로운 에이전트를 추가하고 싶을 때는 다음 명령어를 사용하세요.

openclaw configure
openclaw agents add <name>

QuickStart vs Advanced

Wizard를 시작하면 두 가지 모드 중 하나를 선택할 수 있어요.

• QuickStart (기본값): Local Gateway(18789 포트) 사용, 자동 생성된 Token 인증, coding 툴 프로필 적용, Telegram/WhatsApp allowlist 설정 등을 자동으로 진행해요.
• Advanced (상세 제어): 모드, Workspace, Gateway, Channel, Daemon, Skill 등 모든 단계를 직접 세밀하게 설정해요.

Wizard가 설정하는 항목들

Local mode를 선택하면 다음 7단계 과정을 거치게 돼요.

1. Model/Auth: 사용할 Provider와 모델을 선택해요. OpenAI, Anthropic 호환 모델이나 Custom Provider를 설정할 수 있어요.
2. Workspace: 에이전트 파일이 저장될 위치를 정해요 (기본값: ~/.openclaw/workspace).
3. Gateway: 포트, 주소, 인증 모드(Token/Password), Tailscale 노출 여부를 설정해요.
4. Channels: WhatsApp, Telegram, Discord, Google Chat, Mattermost, Signal, BlueBubbles, iMessage 중 연결할 채널을 골라요.
5. Daemon: 서비스가 백그라운드에서 계속 실행되도록 LaunchAgent(macOS)나 systemd(Linux)를 설치해요.
6. Health check: Gateway를 실행하고 정상적으로 작동하는지 확인해요.
7. Skills: 권장 Skill들과 필요한 의존성 파일들을 설치해요.

[!TIP] Wizard 과정 중에 Web search 단계를 거치게 돼요. Perplexity, Brave, Gemini, Grok, Kimi 중 하나를 선택하고 API 키를 입력하면 에이전트가 web_search 기능을 사용할 수 있어요.

문제 해결

설정 중에 문제가 생겼나요? 당황하지 말고 아래 방법을 시도해 보세요.

• 설정 초기화: 기존 설정을 지우고 다시 시작하고 싶다면 --reset 플래그를 사용하세요. Workspace까지 모두 지우려면 --reset-scope full을 입력하면 돼요.
• 오류 진단: 설정 파일이 유효하지 않거나 예전 버전을 사용 중이라면 Wizard가 openclaw doctor 실행을 요청할 거예요. 이 명령어로 상태를 점검해 보세요.
• Non-interactive 모드: 스크립트에서 자동화를 원한다면 --non-interactive 플래그를 사용하고, API 키 대신 환경 변수를 참조하려면 --secret-input-mode ref를 활용하세요.

---

더 궁금한 점이 있나요? AI Setup Assistant에게 물어보고 설정을 빠르게 마무리하세요!

다음 단계

• CLI 명령어 상세 참조: openclaw onboard
• 온보딩 개요: Onboarding Overview
• macOS 앱으로 시작하기: Onboarding
• 에이전트 초기 실행 가이드: Agent Bootstrapping