2026 OpenClaw 가장 완전한 설치·설정 가이드: 0부터 가동까지 실전 튜토리얼

2. 자주 겪는 함정

1. 제약: 「기동됐다」로 끝나는 설명.터미널 환영 메시지는 모델 연결·파일 도구·게이트웨이 수신을 뜻하지 않습니다. 실사용에는 의존성·Node 버전, onboard·모델, 18789 Gateway, Dashboard, 권한 경계, 로그 추적, 저위험 검수가 모두 통과해야 합니다.
2. 숨은 비용: 키·경로 분산.API Key가 메모에만 있고, openclaw.json5와 .env 불일치, 작업 공간이 홈 전체—한 번의 실수로 SSH 키·본 repo를 망가뜨릴 수 있습니다.
3. 안정성·감사: 로그 위치를 잊음.문제 시 바로 재설치하면 ~/.openclaw/logs/errors.log 단서가 사라집니다. 백업 없는 업그레이드는 설정 롤백도 어렵습니다.

3. 설치 전 준비: Mac·환경 체크리스트

목적:중간에 네트워크·Git·디스크 부족을 발견하지 않도록 합니다.통과 기준: 아래 항목을 모두 충족한 뒤 install 스크립트를 실행합니다.

• 시스템:macOS 12+(Intel/Apple Silicon. 로컬 추론은 Apple Silicon이 유리한 경우가 많으나, 클라우드 모델은 provider 문서를 따릅니다).
• Git:공식 설치기는 안정적인 네트워크·모델 provider 계정을 권장(git --version ≥ 2.30 권장). 없으면 Xcode Command Line Tools 또는 brew install git。
• 네트워크:GitHub raw(install 스크립트)와 선택한 LLM API에 도달 가능해야 합니다. 사내 프록시는 HTTPS_PROXY 을 미리 설정.
• 디스크:공식 install은 Python 3.11, Node.js v22, ripgrep, ffmpeg 등을 가져옵니다. 여유 ≥ 2GB 권장(Skills 캐시 포함 1.5–3GB일 수 있음—당시 문서로 확인).
• 권한:일반 사용자 install에 sudo는 불필요. root로 설치한 적이 있으면 데이터는 /root/.openclaw 일 수 있습니다.
• 백업:기존 ~/.openclaw 이 있으면 cp -a ~/.openclaw ~/.openclaw.bak-$(date +%F)。
• 테스트 디렉터리:격리 작업 공간 ~/openclaw-lab 생성. 첫 실전은 ~/Documents, 본 git·비밀 폴더를 대상으로 하지 마세요.

# 설치 전 빠른 점검(한 블록으로 실행 가능)
git --version
sw_vers
df -h ~
mkdir -p ~/openclaw-lab/{inbox,outbox,archive}
echo "OpenClaw lab sample: Q2 planning notes." > ~/openclaw-lab/inbox/sample.txt

실패 시 먼저 확인:Git 오류 → CLT/Homebrew; 디스크 부족 → Downloads 정리; 타임아웃 → 네트워크 변경. 원인 미확인 채 연속 3회 재설치는 피하세요.

4. 공식 방식으로 OpenClaw 설치

목적:공식이 유지하는 install 진입점으로 Node·CLI를 맡깁니다.출처:공식 Installation 문서(게시 전 버전·추가 플래그 재확인).

4.1 권장: 공식 install.sh(macOS / Linux)

curl -fsSL https://openclaw.ai/install.sh | bash

# 설치만, onboard는 나중에:
# curl -fsSL https://openclaw.ai/install.sh | bash -s -- --no-onboard

설치기가 OS를 감지하고 필요 시 Node(문서 권장 Node 24 또는 Node 22.19+)와 OpenClaw CLI를 설치합니다. 일반 경로(현행 문서 기준, 게시 전 재확인):

• 사용자 설정:~/.openclaw/(openclaw.json5, secrets/, 상태·로그)
• Gateway 기본 포트:18789(로컬 Control UI / WebSocket）
• macOS 상시 실행:openclaw onboard --install-daemon 로 LaunchAgent 등록

4.2 초기화: onboard 마법사

openclaw onboard --install-daemon

# 설치 검증(공식 권장 3종):
openclaw --version
openclaw doctor
openclaw gateway status

마법사에서 모델 provider, API Key, Gateway를 설정합니다. 출처 불명 install 스크립트는 실행하지 마세요. 키를 git·채팅 이미지에 올리지 마세요.

4.3 설치 후 반드시 기록

source ~/.zshrc          # 또는 새 터미널
openclaw --version         # 버전 메모(이후 진단용)
openclaw doctor            # 부족 항목 검출; --fix로 복구 시도 가능

통과 기준: which openclaw 이 PATH상 openclaw(대개 npm 글로벌 bin)를 가리킴; openclaw doctor 에 차단 FAIL 없음.실패 시 먼저 확인: 스크립트 마지막 20줄 → PATH → Node 버전 미달 또는 npm 글로벌 bin 미설정.

주의:실패 직후 「~/.openclaw 삭제 후 재설치」하지 마세요—터미널 출력과 openclaw doctor 를 저장해 네트워크·권한을 구분하세요.

5. 모델·API Key 설정

목적:선택한 LLM provider를 Agent가 호출할 수 있게 합니다.통과 기준: 비대화 스모크에서 타당한 응답; openclaw auth list 또는 .env 에 항목이 있고 shell history에 평문이 남지 않아야 합니다.

5.1 대화형 설정(첫 설치 권장)

openclaw onboard        # 대화 마법사: 모델, 키, Gateway(--install-daemon 병용 가능)
# 키는 auth-profiles/환경 변수로도 주입(공식 Authentication 참고)

5.2 환경 변수·설정 파일

주 설정은 ~/.openclaw/openclaw.json5, 키 참조는 ~/.openclaw/.env이 흔함(openclaw config path, openclaw config env-path 로 실제 경로 확인). 예(변수명은 provider 최신 문서 기준, 오래된 이름을 그대로 복사하지 마세요):

# 예: OpenRouter(본인 key로 교체, git 커밋 금지)
openclaw config set OPENROUTER_API_KEY "sk-or-v1-xxxxxxxx"

# 또는 .env 직접 편집(chmod 600 ~/.openclaw/.env)
echo 'OPENROUTER_API_KEY=sk-or-v1-xxxxxxxx' >> ~/.openclaw/.env

경계:가격·쿼터·지역·프라이버시는 provider마다 다릅니다. 본문은 특정 모델명에 고정하지 않습니다. 운영 전 최신 약관을 확인하세요.

6. 작업 디렉터리·권한·로그

목적:도입 후 「추적·제한·롤백」이 가능한 상태로 만듭니다.원칙:최소 권한—먼저 테스트 dir만, 본 프로젝트는 단계적으로.

• 작업 공간:openclaw.json5 또는 세션에서 ~/openclaw-lab. AGENTS.md 로 허용 도구·경계 기술(공식 Context Files 참고).
• macOS 권한:터미널/파일 도구에서 「전체 디스크 접근」이 뜰 수 있음—첫 검수는 테스트 dir 관련만, 디스크 전체는 피하세요.
• 로그:기본 ~/.openclaw/logs/(agent.log, errors.log, gateway.log).openclaw logs list, openclaw logs errors --since 30m.
• 키 보안:chmod 600 ~/.openclaw/.env; 백업 zip을 동기 드라이브에 두지 않음; Agent가 ~/.ssh, 결제, 본 kubeconfig를 읽지 않게.
• 백그라운드(선택):Telegram/Discord 등은 openclaw gateway setup와 openclaw gateway install. 장기 운영은OpenClaw 7×24 게이트웨이 운영 가이드 참고.

통과 기준: 「~/openclaw-lab만 R/W」 지시 후 홈 밖 경로는 거부되거나 로그에 감사 흔적이 남아야 합니다.

7. Dashboard 열기·Gateway 검증(포트 18789)

목적:Control UI·WebSocket Gateway가 정상인지 확인.통과 기준：로컬 http://127.0.0.1:18789 표시; openclaw gateway status 에서 18789 수신 대기.

openclaw gateway status
openclaw dashboard
# 브라우저 직접 접속:
# http://127.0.0.1:18789/

# 원격 Mac(SSH 포워딩. 18789를 인터넷에 노출하지 마세요):
# ssh -L 18789:127.0.0.1:18789 user@remote-mac

# 포트 점유 진단:
lsof -i :18789
openclaw gateway restart
openclaw doctor --fix

실패 시 먼저 확인:포트 점유 → lsof 로 경합 프로세스 종료; Dashboard는 비지만 status 정상 → 캐시 또는 WebSocket 프록시; 원격 실패 → SSH 로컬 포워딩만인지 확인.launchd:--install-daemon 된 경우 Mac 재시작 후에도 openclaw gateway status 가 running. 아니면 LaunchAgent 로그·사용자 일치 확인(환경 변수·SecretRef·LaunchAgent Runbook).

8. 첫 실행 검수: 7단계 Runbook

다음 7단계로 「설정 완료」에서 「실전 가용」까지. 가능한 그대로 실행하고 출력·로그 일부를 남기세요.

1. 진단:openclaw doctor --fix → 미처리 FAIL 없음.
2. 모델 ping:openclaw agent --message "Reply with exactly: OPENCLAW_OK" → 응답에 OPENCLAW_OK.
3. 파일 읽기:~/openclaw-lab/inbox/sample.txt 를 읽고 첫 줄 요약.
4. 파일 쓰기:~/openclaw-lab/outbox/ping.txt 에 쓰고 cat 로 확인.
5. 로그:openclaw logs errors --since 10m → 신규 ERROR 없음(알려진 무시 항목은 메모).
6. 터미널 재시작:창을 닫고 새로 2단계 재실행 → PATH가 세션 한정이 아닌지 확인.
7. 선택: Mac 재시작:재시작 후 2단계(gateway 설정 시 openclaw gateway status도).

인용 가능한 기준(개인 검수, 공식 SLA 아님):스모크 응답 < 60초; 10분 이내 미설명 ERROR 0; 쓰기 후 ls -la ~/openclaw-lab/outbox 에 새 파일.

9. 첫 실전 사례: 요약 + 할 일 + 롤백 가능한 출력

시나리오:테스트 dir에서 샘플을 읽고 한국어로 150자 이내 요약과 할 일 3개를 Markdown에 쓰고 백업을 남깁니다. 설치(CLI), 설정(모델), workflow(읽기→추론→쓰기→로그)를 한 번에 검증합니다.

# 1. 입력 준비(3절에서 만들었으면 생략 가능)
cat > ~/openclaw-lab/inbox/weekly-notes.txt <<'EOF'
이번 주 완료: OpenClaw 설치 문서 초안.
후속: OpenRouter 예산 알림 설정; 다음 주 Telegram 연동 검토.
리스크: API Key를 git에 커밋하지 않기.
EOF

# 2. 대화 세션 시작
openclaw
# 세션 내 프롬프트 예:
# 「~/openclaw-lab만 사용. inbox/weekly-notes.txt를 읽고, 
#   한국어로 150자 이내 요약과 할 일 3개를 outbox/summary-and-todos.md에 저장하고, 
#   원고를 archive/weekly-notes.bak에 복사」

# 3. 비대화 검수
ls -la ~/openclaw-lab/outbox/summary-and-todos.md
ls -la ~/openclaw-lab/archive/
openclaw logs agent -n 30 --since 15m

통과 기준：

• summary-and-todos.md 에 요약·할 일 3개, 원문과 의미 일치.
• archive/ 에 백업, diff 로 비교 가능.
• 로그에 tool call; provider 청구 화면에 이번 호출(비용 확인).

롤백:rm ~/openclaw-lab/outbox/summary-and-todos.md && cp ~/openclaw-lab/archive/weekly-notes.bak ~/openclaw-lab/inbox/weekly-notes.txt。실패 시 먼저 확인:컨텍스트 잘림·미읽기 → outbox 쓰기 권한 → errors.log의 tool 오류.

10. 트러블슈팅: 계층별 진단, 맹목적 재설치 피하기

게시 전 팩트 체크(편집자용): 공식 install.sh URL, 최소 macOS, 기본 디렉터리, CLI 하위 명령, provider 환경 변수명, 로그 경로—하나라도 바뀌면 문서를 먼저 갱신하세요. 독자는 openclaw doctor → errors.log → 마지막에 재설치 순서만 기억하면 충분합니다.

11. 다음 확장: 테스트 dir → 본 workflow

검수 후 아래 순서로 확장하며, 바로 본 repo·결제에는 연결하지 마세요:

1. 실프로젝트 dir 1개만 화이트리스트. 여전히 ~/.ssh 와 전역 * 읽기/쓰기 금지.
2. openclaw cron 로 저위험 일일 작업(예: 다운로드 목록—대상은 테스트 dir만).
3. 메시징 게이트웨이 1개(Telegram/Discord) 페어링 제한으로 활성화(공식 Security 참고).
4. 주간 openclaw backup --quick 후 장기 운영 글에서 업그레이드/롤백 연습.