OpenClaw를 처음 설치할 때 막히는 이유는 보통 명령어 복사가 아니라, 각 단계가 무엇을 검증하는지 모르기 때문입니다. 터미널 오류 없음, Dashboard 열림, 모델 응답, 파일 쓰기—네 가지는 서로 다른 체크포인트입니다. 이 글은 준비 → 설치 → 설정 → 권한 → Dashboard → 첫 테스트 한 줄로 진행하고, 실패 시 로그를 어디서 볼지까지 정리합니다.
0 이 가이드로 끝낼 일
끝까지 따라오면 네 가지를 확인할 수 있습니다: ① CLI·Gateway 설치, ② 모델 provider·API Key 연결, ③ 브라우저에서 로컬 Control UI 접속, ④ 테스트 디렉터리에서 저위험 읽기·쓰기. 목표는 「설치됨」이 아니라 「통제 가능한 범위에서 동작하고, 오류 시 스스로 점검」입니다.
1 설치 전 준비: Mac, 네트워크, 테스트 폴더
할 일: 손대기 전에 환경을 맞춥니다.이유: 하나라도 빠지면 중간에 반복 시행착오가 납니다.성공 기준: 터미널을 열 수 있고, 공식 설치 문서에 접속할 수 있으며, 테스트 폴더를 만들어 두었습니다.
- 시스템 — macOS(Apple Silicon·Intel 모두). 공식 권장은 Node 24(권장) 또는 Node 22.19+입니다. 공식 설치 스크립트가 Node를 처리하므로 Homebrew는 선택 사항입니다.
- 네트워크·권한 — openclaw.ai와 모델 제공사에 접속 가능해야 합니다. 설치·설정·LaunchAgent에는 관리자 비밀번호가 필요할 수 있습니다.
- 모델 계정 — Anthropic, OpenAI, OpenRouter 등에서 가입 후 API Key를 발급합니다(모델 서비스 자격 증명, 비밀번호와 같음—공유·Git 커밋 금지).
- 테스트 디렉터리 — 예:
~/openclaw-test에notes.txt를 둡니다. 작업 디렉터리는 Agent가 건드릴 수 있는 범위이며, 첫 실행은 여기만 열어두세요.
2 설치: 공식 경로만, 출력은 저장
할 일: OpenClaw CLI와 Gateway를 설치합니다.이유: 비공식 패키지는 변조 위험이 있습니다.성공 기준: openclaw --version에 버전이 나옵니다.
Mac 권장( OS 감지, Node 설치, 온보딩 시작):
curl -fsSL https://openclaw.ai/install.sh | bash
Node를 직접 관리한다면: npm install -g openclaw@latest 후 openclaw onboard --install-daemon(macOS LaunchAgent 백그라운드 서비스).
설치 후 터미널의 버전·전체 출력을 저장하세요(스크린샷·메모). 검증 세 가지:
openclaw --version · openclaw doctor · openclaw gateway status
3 설정: provider, API Key, 설정 파일
용어만 맞춥니다: 모델 provider는 클라우드 제공사(예: Anthropic); API Key는 접근 자격; 환경 변수는 터미널 임시 설정(예: export ANTHROPIC_API_KEY=...); 설정 파일은 ~/.openclaw/openclaw.json(JSON5); 로컬 모델은 Ollama 등 로컬 추론—첫 실행은 클라우드 Key만으로 충분합니다.
온보딩(provider 선택, Key 붙여넣기, 기본 모델):
openclaw onboard --install-daemon
성공 기준: openclaw doctor에 치명적 오류 없음; Dashboard·CLI에서 인사에 모델이 응답.실패 시: Key 전체 복사 여부, 잔액·한도, HTTPS 프록시 차단.
4 권한: 처음엔 테스트 폴더만
할 일: Agent 읽기·쓰기 경로를 제한하고 macOS 권한 팝업을 신중히 처리합니다.이유: 전체 디스크 허용은 Mac 전체를 자동화에 넘기는 것과 같습니다.성공 기준: 테스트는 ~/openclaw-test 안에서만 파일 생성·수정.
「파일 및 폴더」「자동화」「손쉬운 사용」 등 메뉴 이름은 macOS 버전마다 다릅니다—화면에 보이는 대로 확인하세요.
- 테스트 폴더만 선택하고, 처음부터 「전체 디스크」나 iCloud 루트는 주지 마세요.
- 캘린더·연락처·화면 녹화 등 첫 동작 확인과 무관한 권한은 거절하고, 필요할 때만 켭니다.
- Gateway 포트를 공인 인터넷에 노출하지 마세요. 가정망에서는 로컬 또는 VPN만 사용하세요.
5 Dashboard: 로컬 주소와 원격 Mac
할 일: 브라우저로 Control UI를 엽니다.이유: Gateway 실행·세션을 눈으로 확인합니다.성공 기준: 페이지 로드 후 메시지 전송 가능.
터미널에서 openclaw dashboard 또는 http://127.0.0.1:18789/(로컬 전용).
| 증상 | 가능한 원인 | 먼저 할 일 |
|---|---|---|
| 연결 불가 | Gateway 미실행 | openclaw gateway status, 필요 시 openclaw onboard --install-daemon |
| 이 Mac에서만 됨 | 127.0.0.1만 수신 | 원격 Mac: ssh -L 18789:127.0.0.1:18789 user@mac 후 로컬 브라우저에서 위 주소 |
| 주소 맞는데 백화면 | 캐시·확장 | Safari 비공개 창 또는 광고 차단 끄고 재시도 |
로그는 증거입니다. openclaw doctor와 Help / Troubleshooting을 대조하고, 감으로 설정을 바꾸지 마세요.
6 첫 실행: 저위험 테스트
~/openclaw-test/notes.txt에 예: 「프로젝트 코드: Alpha」 두 줄. Dashboard·CLI에 보냅니다:
openclaw-test 폴더의 notes.txt를 읽고 세 문장으로 요약한 뒤, 같은 폴더에 summary.md를 만들어 주세요.
성공 기준: ① 응답이 파일 내용과 일치 ② summary.md 생성 ③ openclaw doctor 정상 ④ 로그에 요청 기록. 쓰기 실패 시 모델보다 macOS 파일 접근 거부를 먼저 보세요.
7 초보자 자주 하는 실수
command not found
PATH에 npm 전역 bin 없음 → ~/.zshrc 수정 후 터미널 재시작.
API Key 무효 / 401
Key 재발급, provider·onboard 선택 일치, 공백 여부 확인.
Dashboard 안 열림
gateway status → 포트·로컬/원격 Mac 혼동 여부.
권한 거부 / 파일 안 씀
시스템 설정 → 개인 정보 보호 → 터미널·OpenClaw에 테스트 폴더만, 전체 디스크 금지.
테스트 통과 후에야 실제 프로젝트 폴더, Telegram/Slack, 캘린더·미리 알림을 단계적으로 연결하세요. 매번 「작은 범위 시험 → 로그 확인 → 확대」를 반복합니다.
- 1허용 경로를 테스트 폴더에서 비프로덕션 repo 하나로 확장
- 2
openclaw.json에 채널 화이트리스트(예:allowFrom) 추가 - 324/7 필요 시 LaunchAgent 자동 시작 확인, 정기적으로
openclaw doctor
8 Mac mini에서 OpenClaw를 돌리면 더 편합니다
OpenClaw는 셀프호스팅 Gateway입니다. 상시 가동과 권한 경계를 동시에 맞추려면 주력 MacBook보다 전용 머신이 낫습니다. Mac mini M4는 소형·대기 전력 약 4W급·24/7 무소음에 적합하고, macOS Unix 환경에서 공식 설치 스크립트·LaunchAgent·SSH 유지보수가 수월합니다. Gatekeeper, SIP, FileVault로 전용 계정·테스트 폴더에 Agent를 가두기도 쉽습니다. 가정·소규모 팀 상시 노드라면 Mac mini M4가 비용 대비 명확한 선택입니다—먼저 로컬 Mac에서 테스트를 통과한 뒤, 전용 Mac mini로 이전해 장기 운영하세요. 지금이 Mac mini M4를 검토하기 좋은 시점입니다.
OpenClaw 상시 · 저전력 24/7Mac mini로 OpenClaw 노드를 만드세요
빠른 개통 · 원격 SSH · 안정 네트워크 · AI Gateway·Dashboard 장기 운영에 적합.