OpenClaw를 설치하고 나서 "이제 어떻게 AI와 대화를 시작하지?"라는 막막함, 느끼셨나요? 설치만 마친 상태의 OpenClaw는 뇌가 아직 연결되지 않은 잠자는 프로그램에 불과합니다. 파이썬 기초 지식만 가진 직장인이나 AI 자동화 입문자라면 이 단계에서 멈춰버리는 경우가 많습니다.
이번 3편에서는 openclaw 온보딩을 처음부터 끝까지 다룹니다. openclaw onboard 명령어로 초기 설정 마법사를 실행하고, 원하는 AI 모델을 연결한 뒤, 게이트웨이를 가동하여 나만의 프라이빗 AI 비서와 첫 대화를 나누는 전 과정을 직접 따라 하실 수 있습니다.
지난 편(이전: OpenClaw 설치 완전 가이드 — macOS·Windows·WSL2 환경별 정리)에서는 macOS·Windows·WSL2 환경별 설치 방법을 다뤘습니다. 아직 설치를 완료하지 않으셨다면 2편을 먼저 확인해 주세요.
openclaw 온보딩이란? — 초기 설정 마법사 개념과 실행
openclaw 온보딩(Onboarding)은 새 스마트폰을 처음 샀을 때 언어, 와이파이, 구글 계정을 설정하는 초기 세팅 과정과 정확히 같은 개념입니다. OpenClaw가 어떤 AI 모델을 사용할지, 보안 토큰은 무엇으로 할지를 단계별로 물어보며 기초 환경을 구성해 줍니다.
이전 편에서 공식 설치 스크립트로 설치했다면 설치 직후 온보딩이 자동으로 실행되었을 수 있습니다. 하지만 수동 설치를 했거나 설정을 처음부터 다시 하고 싶을 때는 아래 명령어를 언제든지 실행할 수 있습니다.
온보딩 명령어 실행
터미널을 열고 아래 명령어를 그대로 복사하여 실행하세요. 화면에 단계별 질문이 차례로 나타납니다.
# OpenClaw 초기 설정 마법사(온보딩) 실행
openclaw onboard
📎 OpenClaw 공식 문서 (Get Started) 보기 →
openclaw onboard는 언제든 재실행 가능한 초기 설정 마법사입니다. AI 모델 선택과 보안 토큰 설정, 이 두 가지가 핵심입니다.AI 모델(Provider) 연결하기 — Claude·GPT·Ollama 선택 가이드
셀프호스팅 AI의 가장 큰 장점은 내가 원하는 인공지능 모델을 자유롭게 선택할 수 있다는 것입니다. 온보딩 마법사 중간에 어떤 제공자(Provider)를 사용할지 묻는 단계가 나오는데, 현재 상황에 맞는 선택이 중요합니다.
Provider별 특징 비교
각 제공자의 특성을 파악하고 자신에게 맞는 모델을 선택하세요.
- Anthropic (Claude): 공식적으로 가장 권장되며 코딩과 논리적 작업에 매우 뛰어납니다. API 키 형식:
sk-ant-xxx... - OpenAI (GPT-4o 등): 범용적으로 가장 널리 쓰이고 다양한 작업에 무난한 선택입니다. API 키 형식:
sk-xxx... - Ollama (로컬 모델): 내 컴퓨터 자원만 사용하여 100% 무료로 운영하고, 외부로 데이터가 전송되지 않아 프라이버시 보호에 최적입니다.
API 키가 없거나 비용 부담 없이 먼저 전체 흐름을 파악하고 싶다면 Ollama 로컬 모델로 시작한 후 상용 API로 전환하는 방법을 추천합니다.
게이트웨이 실행부터 첫 AI 대화까지 — 단계별 가이드
온보딩을 완료했다면 이제 OpenClaw의 심장인 게이트웨이(Gateway)를 가동할 차례입니다. 아래 순서대로 따라 하시면 5분 내에 첫 AI 대화까지 완료됩니다.
- 온보딩 마법사 실행 및 Provider 선택터미널에서
openclaw onboard를 실행하고, 화면에 나타나는 번호 목록에서 사용할 AI 모델(Provider)을 선택합니다. openclaw onboard- API 키 또는 로컬 모델 설정상용 API(Claude, GPT)를 선택했다면 각 플랫폼에서 발급받은 API Key를 입력합니다. Ollama를 선택했다면 별도 키 입력 없이 다음 단계로 넘어갑니다.
# Anthropic API 키 예시 sk-ant-api03-xxxxxxxxxxxxxxxxxxxxxxxx- 보안 토큰(Token) 설정웹 패널 접속 시 사용할 보안 토큰을 설정합니다. 이 토큰은 반드시 안전한 곳에 기록해 두세요. 이 과정까지 완료되면 온보딩이 마무리됩니다.
- 게이트웨이 실행 및 웹 패널 접속터미널에서 아래 명령어로 게이트웨이 서버를 실행합니다. 정상 실행 로그가 확인되면 브라우저에서
http://localhost:18789로 접속하고, 설정한 보안 토큰을 입력하면 AI 채팅 패널이 열립니다. # OpenClaw 게이트웨이 서비스 시작 openclaw gateway
API 키 안전 관리와 설정 파일 이해
온보딩 마법사로 설정한 모든 정보는 로컬 설정 파일에 저장됩니다. 이 파일의 위치와 구조를 알아두면 나중에 설정을 변경하거나 문제를 해결할 때 큰 도움이 됩니다.
설정 파일 직접 수정하기
온보딩 마법사를 재실행하지 않고도 설정 파일을 직접 편집할 수 있습니다. 기본 설정 파일은 아래 경로에 위치합니다.
# 설정 파일 위치 확인 및 편집
~/.openclaw/openclaw.json
# 환경 변수로 API 키 안전하게 관리하는 예시 (bash/zsh)
export ANTHROPIC_API_KEY="sk-ant-api03-xxxxxxxxxx"
실전 팁과 주의사항
- 온보딩 언제든 재실행 가능: 설정이 잘못됐다고 느끼면
openclaw onboard를 다시 실행하면 됩니다. 기존 설정을 덮어쓰므로 걱정 없이 재시도하세요. - Ollama로 무료 테스트 먼저: API 키 발급이 번거롭다면 Ollama 로컬 모델로 전체 흐름을 먼저 익히고, 익숙해진 후 상용 API로 전환하는 순서를 권장합니다.
- 보안 토큰 반드시 기록: 온보딩 시 설정한 보안 토큰을 분실하면 재온보딩이 필요합니다. 패스워드 매니저나 안전한 메모에 꼭 저장해 두세요.
- 포트 충돌 사전 확인: 게이트웨이 실행 전, 18789 포트가 이미 다른 프로그램에 점유되어 있지 않은지 미리 확인하세요. (
lsof -i :18789명령어로 확인 가능)
자주 묻는 질문 (FAQ)
- 온보딩 중에 실수로 API 키를 잘못 입력했는데 어떡하나요?
- 당황하지 마세요! 터미널에서 언제든지
openclaw onboard명령어를 다시 실행하면 설정을 덮어쓸 수 있습니다. 더 익숙해지면~/.openclaw/openclaw.json설정 파일을 직접 열어 수정하는 것도 가능합니다. - Claude나 GPT 같은 API 키는 어디서 발급받나요? 무료로도 가능한가요?
- 상용 모델 API 키는 Anthropic Console이나 OpenAI Developer Platform 웹사이트에서 회원가입 후 카드 등록을 통해 발급받을 수 있으며, 사용한 만큼만 비용이 청구됩니다. 완전 무료로 테스트하고 싶다면 내 컴퓨터에서 직접 실행되는 'Ollama' 로컬 모델 연동 방식을 추천합니다.
- 게이트웨이를 켰는데 localhost:18789가 열리지 않아요. 어떻게 해야 하나요?
- 가장 흔한 원인은 18789 포트를 다른 프로그램이 이미 사용 중이거나, 터미널에서 게이트웨이 실행 명령어가 에러로 중단된 경우입니다. 터미널 에러 로그를 먼저 확인하고, 해결되지 않는다면 다음 편 openclaw doctor에서 다루는 진단 명령어를 활용해 보세요.
- 코딩을 전혀 몰라도 온보딩을 완료하고 첫 AI 대화를 할 수 있나요?
- 물론입니다! 온보딩 마법사는 화면에 나오는 질문에 번호를 선택하고 엔터만 치면 되도록 직관적으로 설계되어 있어, 파이썬 기초 지식만 있어도 전체 과정을 충분히 따라오실 수 있습니다.
이 글이 도움이 됐다면 댓글로 여러분의 경험을 알려주세요! 🙌
openclaw 온보딩에서 막히는 부분은 댓글에 남겨주세요 — 직접 답변드립니다.
📬 새 편 알림 받기 → AI 활용 가이드 구독
'OpenClaw' 카테고리의 다른 글
| [openclaw 완전 가이드] 4편 openclaw 오류 해결의 만병통치약! doctor 명령어와 설치 진단 총정리 (0) | 2026.03.27 |
|---|---|
| [OpenClaw 완전 가이드 2편] 설치 방법 — macOS·Windows·WSL2 환경별 완벽 정리 (0) | 2026.03.26 |
| [openclaw 완전 가이드 1편] openclaw란 무엇인가? 셀프호스팅 AI 에이전트 만들기 입문 (0) | 2026.03.26 |
댓글