2026. 2. 11. 02:11ㆍAI 기술/OpenClaw
OpenClaw 설치부터 온보딩, 첫 대화, 실전 워크플로우, 운영 보안까지 한 번에 정리했습니다. npm 명령어 한 줄이면 설치가 끝나고, 온보딩 마법사가 나머지를 안내합니다. OpenClaw 완벽 가이드 시리즈 4부입니다.
OpenClaw 완벽 가이드 시리즈 4/5
← 이전 글: 3부 — Claude·Gemini API 키 발급
드디어 OpenClaw를 설치하고, 처음으로 "내 AI 비서"와 대화하는 시간입니다.
1~3부에서 환경 세팅과 API 키를 준비했으니, 이제 실제로 설치하고 구동하는 건 놀라울 정도로 간단합니다. 명령어 2줄이면 설치가 끝나고, 온보딩 마법사가 나머지를 알아서 안내해줍니다.
이 글에서는 설치 → 온보딩 → 첫 대화 → 실전 워크플로우 → 운영 팁까지, OpenClaw를 "매일 쓰는 자동화 비서"로 만드는 과정을 한 번에 다룹니다.
목차
1. 설치 전 최종 확인
2. OpenClaw 설치 (npm 한 줄)
3. 온보딩 마법사 실행
4. Gateway & Control UI 확인
5. 에이전트와 첫 대화
6. 자주 쓰는 CLI 명령어 모음
7. 실전 워크플로우 5선
8. 운영 & 보안 가이드
9. 트러블슈팅 FAQ
10. 시리즈를 마치며
1. 설치 전 최종 확인
설치를 시작하기 전에, 1~3부에서 준비한 환경이 모두 정상인지 30초만 확인합니다.
# WSL(Ubuntu) 터미널에서 실행
node -v # v22.x.x 이상 ← 필수!
npm -v # 10.x.x 이상
echo $ANTHROPIC_API_KEY # sk-ant-... 출력되면 OK
echo $GEMINI_API_KEY # AIza... 출력되면 OK하나라도 빈 값이 나오면? 이전 글을 참고해서 해결하고 오세요. Node 22 미만이면 설치가 실패하고, API 키가 없으면 온보딩에서 모델 연결이 안 됩니다.
2. OpenClaw 설치 (npm 한 줄)
환경이 준비되었다면, 설치는 정말 간단합니다. WSL Ubuntu 터미널에서 아래 명령어 한 줄을 실행하세요.
# OpenClaw 글로벌 설치 (약 1~2분 소요)
npm install -g openclaw@latest설치가 완료되면 openclaw 명령어를 사용할 수 있습니다. 아래 명령으로 설치를 확인합니다.
# 설치 확인
openclaw --version
# openclaw/2026.2.x 형태로 버전이 출력되면 성공command not found 에러가 뜨면? 터미널을 완전히 닫고 새로 여세요. npm 글로벌 설치 후 PATH가 갱신되지 않아 발생하는 문제입니다. 그래도 안 되면 npm bin -g 명령으로 글로벌 경로를 확인한 뒤, 해당 경로를 ~/.bashrc의 PATH에 추가하세요.
pnpm을 선호하는 경우
npm 대신 pnpm을 사용해도 됩니다. pnpm은 npm보다 디스크 공간을 절약하고 설치 속도가 빠릅니다. 다만 추가 설정이 필요합니다.
# pnpm으로 설치하는 경우
npm install -g pnpm # pnpm 먼저 설치
pnpm add -g openclaw@latest # OpenClaw 설치
pnpm approve-builds -g # 빌드 스크립트 승인3. 온보딩 마법사 실행
설치만으로는 아직 OpenClaw가 작동하지 않습니다. 온보딩 마법사를 실행해서 AI 모델 연결, Gateway 설정, 데몬 설치까지 한 번에 완료해야 합니다.
# 온보딩 마법사 실행 (데몬 자동 설치 포함)
openclaw onboard --install-daemon마법사가 시작되면 아래 항목을 순서대로 물어봅니다. 각 단계별로 어떻게 선택하면 좋은지 안내합니다.
3-1. AI 모델 선택
사용할 모델 제공자(Provider)와 모델을 선택합니다. 3부에서 API 키를 준비한 모델을 선택하세요.
| 선택지 | 추천 모델 | 특징 |
|---|---|---|
| Anthropic (Claude) | Claude Sonnet 4.5 | 한국어 우수, 가성비 좋음 |
| Google (Gemini) | Gemini 2.5 Flash | 무료 티어 넉넉, 빠른 응답 |
| OpenAI (GPT) | GPT-4o | 범용성 높음 |
| Ollama (로컬) | Llama 3.x | API 키 불필요, GPU 필요 |
팁: 처음이라면 Claude Sonnet 4.5를 추천합니다. OpenClaw 공식 문서에서도 Anthropic 모델을 "long-context strength and better prompt-injection resistance"로 권장하고 있습니다. 나중에 모델을 바꾸거나 추가하는 건 설정 파일 한 줄 수정으로 가능합니다.
3-2. API 키 연결
환경변수에 키를 등록해뒀다면 마법사가 자동으로 감지합니다. "Use existing environment variable?"라는 질문에 Yes를 선택하면 됩니다. 키를 등록하지 않았다면 여기서 직접 입력할 수도 있습니다.
3-3. Gateway 포트 & 데몬
기본 포트는 18789입니다. 특별한 이유가 없으면 그대로 Enter를 누르세요. --install-daemon 옵션 덕분에 systemd 서비스(WSL/Linux)가 자동으로 등록되어, PC를 켤 때마다 OpenClaw가 자동으로 시작됩니다.
3-4. 채널 연결 (선택사항)
Telegram, Discord, Slack 등 메신저 봇을 연결할 수 있습니다. 지금 당장 연결하지 않아도 되며, 나중에 설정 파일에서 언제든 추가할 수 있습니다. 처음에는 건너뛰고 WebChat(웹 UI)으로 먼저 테스트하는 것을 권장합니다.
4. Gateway & Control UI 확인
온보딩이 끝나면 Gateway가 자동으로 시작됩니다. 아래 방법으로 정상 작동을 확인합니다.
방법 1: 브라우저로 확인
웹 브라우저를 열고 http://localhost:18789에 접속합니다. Control UI 대시보드가 나타나면 성공입니다! 여기서 채팅, 설정, 로그 확인 등 모든 관리가 가능합니다.
방법 2: CLI로 확인
# Gateway 상태 확인
openclaw doctor
# 정상이면 아래처럼 출력:
# ✓ Gateway is running on port 18789
# ✓ Model provider: anthropic (connected)
# ✓ Agent: main (ready)방법 3: 디버그 모드 (문제 발생 시)
# 상세 로그와 함께 Gateway를 수동으로 실행
openclaw gateway --port 18789 --verbose축하합니다! Control UI가 열리면 "내 PC에서 돌아가는 AI 비서"의 설치가 완료된 것입니다. 이제 에이전트에게 첫 번째 메시지를 보내봅시다!
5. 에이전트와 첫 대화
OpenClaw와 대화하는 방법은 세 가지가 있습니다. 어떤 방법이든 같은 에이전트와 대화하며, 대화 히스토리도 공유됩니다.
방법 A: CLI에서 바로 대화 (가장 빠름)
# 에이전트에게 질문하기
openclaw agent --message "안녕! 넌 뭘 할 수 있어?" --thinking high
# --thinking high: 깊은 추론 모드 (복잡한 질문에 추천)
# --thinking low: 빠른 응답 모드 (간단한 질문에 추천)방법 B: WebChat (Control UI)
http://localhost:18789의 Control UI에서 채팅 인터페이스를 사용합니다. ChatGPT 같은 느낌으로 대화할 수 있어서 가장 직관적입니다.
방법 C: 메신저 채널 (Telegram, Discord 등)
온보딩에서 채널을 연결했다면, 해당 메신저에서 바로 대화할 수 있습니다. "아침에 텔레그램으로 오늘 할 일을 물어보는" 같은 루틴이 가능해집니다.
첫 대화 추천 질문: "내가 어떤 명령을 쓸 수 있는지 알려줘", "오늘 날씨를 알려줘", "간단한 파이썬 코드 하나 짜줘" 같은 가벼운 질문으로 시작해보세요. 에이전트가 정상적으로 응답하면 모든 설정이 제대로 된 것입니다.
6. 자주 쓰는 CLI 명령어 모음
OpenClaw를 매일 사용하다 보면 자주 쓰게 되는 명령어들입니다. 이 표를 북마크해두면 편리합니다.
| 카테고리 | 명령어 | 설명 |
|---|---|---|
| 진단 | openclaw doctor |
전체 시스템 건강 상태 점검 |
| 대화 | openclaw agent --message "질문" |
에이전트에게 직접 질문 |
| 메시지 | openclaw message send --to +82... --message "내용" |
연결된 채널로 메시지 전송 |
| 로그 | openclaw logs --follow |
실시간 로그 스트리밍 |
| 업데이트 | npm install -g openclaw@latest |
최신 버전으로 업데이트 |
| 재시작 | openclaw gateway restart |
Gateway 데몬 재시작 |
| 설정 | nano ~/.openclaw/openclaw.json |
설정 파일 직접 편집 |
채팅에서 쓰는 슬래시 명령
WebChat이나 메신저에서 에이전트와 대화할 때 사용할 수 있는 특수 명령입니다.
| 명령 | 기능 |
|---|---|
/status |
현재 세션 상태(모델, 토큰 사용량) 확인 |
/new 또는 /reset |
세션 초기화 (새 대화 시작) |
/compact |
대화 컨텍스트 요약/압축 (토큰 절약) |
/usage |
현재까지 사용한 토큰/비용 표시 |
7. 실전 워크플로우 5선
"설치했는데 뭘 시켜야 할지 모르겠다"는 분들을 위해, 바로 복사해서 쓸 수 있는 실전 워크플로우 5가지를 준비했습니다.
워크플로우 1: 아침 업무 브리핑
매일 아침, 오늘 해야 할 일을 정리받는 루틴입니다.
openclaw agent --message "오늘 일정과 할 일을 10줄로 브리핑해줘. \
(1)긴급 (2)중요 (3)미뤄도 됨으로 분류하고, \
각 항목에 예상 소요 시간도 표시해줘" --thinking high워크플로우 2: 기술 리서치 자동화
특정 기술에 대해 핵심만 빠르게 파악할 때 유용합니다.
openclaw agent --message "EtherCAT 통신 프로토콜을 \
①핵심 개념 ②장점 ③단점/리스크 ④실무 적용 팁 \
순서로 1,000자 내로 정리해줘" --thinking high워크플로우 3: 블로그/보고서 초안 생성
키워드만 주면 구조화된 문서 초안을 만들어줍니다.
openclaw agent --message "아래 키워드로 블로그 글 초안을 만들어줘. \
구조: 서론/목차/본문/FAQ/체크리스트/참고링크 \
키워드: 로컬 AI 에이전트, 멀티채널 봇, 보안 주의사항" --thinking high워크플로우 4: 에러 디버깅 도우미
에러 메시지를 붙여넣으면 원인 분석과 해결 순서를 제안합니다.
openclaw agent --message "아래 에러 로그를 분석해서 \
원인 후보 3개와 확인 순서를 제안해줘. \
마지막에 재현 가능한 체크리스트도 만들어줘. \
에러: npm ERR! code ENOENT" --thinking high워크플로우 5: 운영 체크리스트 생성
정기적인 점검 항목을 자동으로 생성합니다.
openclaw agent --message "OpenClaw를 안전하게 운영하기 위한 \
주간 체크리스트 15개를 만들어줘. \
(키 관리/보안 정책/스킬 검증/업데이트/백업 포함)" --thinking high활용 팁: 위 명령어들을 쉘 스크립트(.sh 파일)로 저장해두면 매일 한 번 실행하는 것만으로 자동 브리핑을 받을 수 있습니다. 크론(cron)과 조합하면 완전 자동화도 가능합니다.
8. 운영 & 보안 가이드
OpenClaw는 내 PC에서 셸 명령 실행, 파일 접근, 브라우저 자동화까지 할 수 있는 강력한 도구입니다. 그만큼 보안에 신경 쓰지 않으면 위험할 수 있습니다. 아래 3가지 원칙을 꼭 지켜주세요.
원칙 1: 입력 통제 — 외부 메시지를 항상 불신하기
OpenClaw가 메신저에 연결되면, 누군가 DM으로 악의적인 명령을 보낼 수 있습니다. Pairing 모드를 유지하고, 승인된 사용자만 에이전트를 호출할 수 있도록 allowlist를 최소화하세요.
# 설정 파일에서 consent mode 활성화 (명령 실행 전 승인 요청)
# ~/.openclaw/openclaw.json
"exec": { "ask": "on" } ← 이 설정이 켜져 있으면
# 파일 삭제, 명령 실행 전에 사용자 승인을 요청합니다원칙 2: 스킬 위생 — 검증된 것만 설치하기
OpenClaw는 "스킬"이라는 플러그인 시스템을 지원합니다. 편리하지만, 출처를 모르는 스킬은 시스템 전체에 접근할 수 있는 보안 위험입니다. 반드시 공식 문서나 GitHub에서 출처를 확인한 후 설치하세요.
원칙 3: 실행 격리 — WSL/VM에서 분리 운영
OpenClaw를 메인 윈도우가 아닌 WSL 안에서 운영하는 것 자체가 이미 좋은 격리입니다. 더 강력한 격리가 필요하면 Docker 컨테이너나 별도 서버(VPS)에서 운영하는 것도 고려하세요.
일상 운영 체크리스트
| 주기 | 할 일 | 명령어/방법 |
|---|---|---|
| 매일 | Gateway 정상 작동 확인 | openclaw doctor |
| 주 1회 | 로그 확인 (이상 동작 점검) | openclaw logs --follow |
| 주 1회 | OpenClaw 업데이트 확인 | npm install -g openclaw@latest |
| 월 1회 | API 키 사용량 & 비용 확인 | Anthropic/Google 콘솔 |
| 월 1회 | 설정 파일 백업 | cp -r ~/.openclaw ~/backup/ |
9. 트러블슈팅 FAQ
Q. npm install -g openclaw@latest에서 권한 에러(EACCES)가 나요
npm 글로벌 설치 경로에 권한이 없는 경우입니다. nvm으로 Node를 설치했다면 이 문제가 발생하지 않습니다(방법 A). 또는 npm 글로벌 디렉토리를 사용자 폴더로 변경할 수 있습니다(방법 B).
# 방법 B: npm 글로벌 디렉토리 변경
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrcQ. 온보딩은 끝났는데 localhost:18789에 접속이 안 돼요
1) Gateway가 실행 중인지 확인: openclaw doctor
2) 포트 충돌 확인: lsof -i :18789 — 다른 프로그램이 해당 포트를 쓰고 있으면 openclaw gateway --port 18790으로 포트를 변경하세요.
3) WSL에서 실행 중이라면 윈도우 브라우저에서 localhost:18789로 접속이 가능합니다. (WSL2는 기본적으로 localhost를 호스트와 공유합니다.)
Q. 모델 응답이 없고 "0 tokens used"라고 나와요
API 인증 실패입니다. API 키에 불필요한 공백이나 줄바꿈이 포함되지 않았는지 확인하고, Anthropic 사용자는 Billing 페이지에서 크레딧 잔액을 확인하세요($0이면 충전 필요). 키를 새로 발급받아 환경변수를 교체한 뒤 Gateway를 재시작해보세요.
Q. 모델을 바꾸고 싶어요 (Claude → Gemini 등)
설정 파일을 직접 편집하면 됩니다.
nano ~/.openclaw/openclaw.json
# "model" 항목을 원하는 모델로 변경
# 예: "provider": "google", "model": "gemini-2.5-flash"
# 변경 후 Gateway 재시작
openclaw gateway restartQ. OpenClaw 업데이트는 어떻게 하나요?
# 최신 버전으로 업데이트
npm install -g openclaw@latest
# 업데이트 후 건강 체크
openclaw doctor업데이트 전에 릴리즈 노트를 확인하는 습관을 들이면, 어떤 변경이 있었는지 미리 파악할 수 있습니다.
Q. Telegram/Discord 봇은 어떻게 연결하나요?
채널 연결은 각 플랫폼의 봇 토큰을 발급받은 뒤, ~/.openclaw/openclaw.json의 channels 섹션에 추가하면 됩니다. 자세한 방법은 공식 채널 설정 문서를 참고하세요. 초보자에게는 Telegram이 가장 쉽습니다 (BotFather에서 토큰 발급 → 설정에 추가 → 재시작).
10. 시리즈를 마치며
4편에 걸쳐 OpenClaw의 개념부터 환경 세팅, API 키 발급, 설치, 실전 활용까지 모두 다루었습니다. 지금까지의 여정을 정리하면 이렇습니다.
| 편 | 주제 | 핵심 내용 |
|---|---|---|
| 1부 | 프롤로그 | OpenClaw란? 핵심 기능, ChatGPT와의 차이점, 보안 주의사항 |
| 2부 | 환경 세팅 | PowerShell, WSL2, Chocolatey, Node.js 22+ 설치 |
| 3부 | API 키 발급 | Claude & Gemini 키 발급, 보안 3원칙, 환경변수 세팅 |
| 4부 | 설치 & 실전 | npm 설치, 온보딩, 첫 대화, 워크플로우 5선, 운영 보안 |
다음 단계 추천:
1. 매일 아침 업무 브리핑 루틴을 만들어보세요 (워크플로우 1번)
2. Telegram이나 Discord 봇을 연결해서 메신저에서 바로 호출해보세요
3. OpenClaw 스킬 문서를 읽고 브라우저 자동화, 파일 관리 같은 고급 기능을 탐색해보세요
4. GitHub에서 커뮤니티 활동과 최신 업데이트를 팔로우하세요
OpenClaw 시리즈가 도움이 되셨다면, 댓글이나 공유로 알려주세요! 추가로 다뤘으면 하는 주제가 있다면 댓글로 남겨주시면 후속 글로 작성하겠습니다.
참고 자료: OpenClaw 공식 문서 · 설치 가이드 · 공식 FAQ · GitHub 저장소 · npm 패키지
이 글은 공식 문서 기반으로 실사용 관점에서 재구성한 정리글입니다. UI/정책은 업데이트로 바뀔 수 있으니 공식 문서를 함께 참고하세요.
'AI 기술 > OpenClaw' 카테고리의 다른 글
| OpenClaw 완벽 가이드 시리즈 5/5 — 최종편 (0) | 2026.02.11 |
|---|---|
| OpenClaw 완벽 가이드 시리즈 3/5 (1) | 2026.02.11 |
| OpenClaw 완벽 가이드 시리즈 2/5 (0) | 2026.02.11 |
| OpenClaw 완벽 가이드 시리즈 1/5 (1) | 2026.02.11 |
| OpenClaw 완벽 가이드: 2026년 가장 핫한 AI 에이전트, 설치부터 활용까지 (1) | 2026.02.11 |