처음 `openclaw`를 설치할 때 막히는 지점은 보통 “설치”가 아니라 “환경”입니다.
프록시나 CPU 아키텍처를 한 번 놓치면, 10분짜리가 1시간이 되기도 하더라고요. 아래는 환경 점검부터 설치, 실행 확인(검증 루틴)까지 한 번에 끝내는 흐름입니다.
—
시작 전 점검
설치 전에 아래 3가지만 확인해두면 실패 확률이 확 내려갑니다. OS/아키텍처, 네트워크, 그리고 기존 런타임입니다.
– 지원 운영체제/아키텍처: 내 PC가 `x86_64`인지 `arm64`인지부터 확인합니다(지원 범위는 배포판/릴리스 노트 기준으로 달라질 수 있어요).
– 권한/네트워크: 회사 망이면 프록시/방화벽 때문에 다운로드·업데이트가 막히는 경우가 흔합니다.
– 기존 런타임/패키지 관리자: `brew`, `apt`, `pip`, `node`, `java` 등이 이미 있으면 버전 충돌이 날 수 있어요(버전을 미리 찍어두면 추적이 빨라집니다).
바로 쓰는 확인 명령 템플릿(필요한 것만 골라 실행):
“`bash
macOS / Linux
uname -a
uname -m
echo “$SHELL”
echo “$PATH”
“`
“`powershell
Windows PowerShell
$PSVersionTable.PSVersion
$env:PROCESSOR_ARCHITECTURE
$env:Path
“`
체크리스트(이거만 채우고 가도 됩니다):
☐ OS: (예: macOS / Ubuntu / Windows)
☐ CPU: (예: `arm64` / `x86_64`)
☐ 설치 방식 후보: (패키지 관리자 / 바이너리 / 소스 빌드)
☐ 네트워크 제약: (프록시 있음/없음, 외부 다운로드 가능/불가)
☐ 기존 설치 흔적: (예: 예전에 깔았다가 지운 적 있음)
—
설치 경로 고르기
점검이 끝나면 설치 방식을 정합니다. 개인 PC는 “편한 게 최고”로 가도 되지만, 팀/서버까지 생각하면 “재현 가능한 방식”이 결국 이깁니다.
설치 방식 비교표:
| 방식 | 장점 | 단점 | 추천 상황 |
|---|---|---|---|
| 패키지 관리자 | 업데이트/제거가 간단 | 저장소 버전이 늦을 수 있음 | 개인 PC, 표준화된 팀 |
| 바이너리 직접 설치 | 빠르고 단순, 의존성 적을 때 편함 | 무결성/업데이트 관리가 본인 몫 | CI 없이 단독 운영, 급히 테스트 |
| 소스 빌드 | 환경에 맞춘 최적화 가능 | 시간 오래 걸림, 빌드 도구 필요 | 특수 환경(제한망/커스텀) |
실무에서 자주 보는 실수 하나는 “일단 시스템 영역에 깔자”입니다. 권한이 꼬이거나 다른 프로젝트와 충돌하고, 나중엔 지우기도 애매해져요.
PATH 전략은 이렇게 잡아두면 편합니다.
– 사용자 영역: `~/.local/bin`(Linux), `/usr/local/bin` 또는 `~/bin`(macOS), 사용자 프로필 경로(Windows)
– 시스템 영역: 여러 사용자가 공유해야 할 때만, 그리고 문서로 남길 때만
짧게 정리하면 이런 느낌입니다.
> 동료: “서버에도 올릴 거야?”
> 나: “네.”
> 동료: “그럼 패키지 관리자나 스크립트로 고정하자. 바이너리는 나중에 누가 업데이트했는지 모른다…”
—
기본 설치
안전한 순서는 “무결성 확인 → 설치 → PATH/환경 변수 → 최소 권한”입니다.
관리자 권한은 마지막 카드로 남겨두세요. 예전에 캐시 꼬임을 잡겠다고 권한만 올렸다가 설정 폴더가 루트 소유로 바뀌어서 더 크게 터진 적도 있습니다(진짜로요).
1) 다운로드/설치 파일 확인(가능하면)
– 릴리스에서 해시(예: `SHA256`)나 서명 정보가 제공되면 먼저 확인합니다.
– 제공이 없다면 최소한 “출처/파일명/버전”을 기록해두세요(나중에 롤백할 때 구명줄이 됩니다).
2) 설치(방식별로 달라집니다)
– 패키지 관리자 설치라면 팀에서는 “버전 고정”이 핵심입니다(예: 특정 버전 설치, 업데이트 정책 합의).
– 바이너리 설치라면 실행 파일을 한 곳(예: `~/.local/bin`)에 모아두는 게 관리가 쉽습니다.
3) PATH/환경 변수 설정
– 셸 설정 파일에 추가합니다. macOS/Linux는 보통 `~/.zshrc` 또는 `~/.bashrc` 쪽입니다.
“`bash
예시: 사용자 바이너리 경로 추가
export PATH=”$HOME/.local/bin:$PATH”
“`
- 권한 오류가 날 때의 안전한 해결 순서
– ( - 설치 위치가 사용자 영역인지 확인
– ( - 파일 권한/소유자 확인
– ( - 그래도 안 되면 그때 “필요한 범위에서만” 관리자 권한 사용
—
검증 루틴
설치 성공 여부는 보통 “버전/도움말 → 가장 작은 샘플 실행 → 로그 준비” 3단에서 갈립니다.
처음엔 귀찮았는데, 한 번 루틴으로 만들어두면 장애가 났을 때 재현이 빨라져서 오히려 편합니다.
1) 버전 확인 & 도움말 호출
“`bash
openclaw –version
openclaw –help
“`
2) 간단 샘플 실행(가능한 최소 단위)
– 목표는 “동작한다”가 아니라, “의존성이 빠졌는지”를 빨리 잡는 겁니다.
– 샘플/서브커맨드가 있다면 제일 가벼운 걸로 한 번만 돌립니다.
“`bash
예시 형태(프로젝트/버전마다 다를 수 있고, 해당 서브커맨드가 없을 수도 있음)
openclaw doctor
openclaw run –dry-run
“`
3) 로그 위치/레벨 잡아두기
– 실패했을 때 로그가 어디 찍히는지 모르면, 같은 문제를 두 번 겪습니다.
– 환경 변수나 플래그로 로그 레벨을 올릴 수 있다면 “재현할 때만” 올리는 게 깔끔합니다.
“`bash
예시 형태(변수/플래그 이름은 프로젝트마다 다를 수 있음)
export OPENCLAW_LOG=debug
openclaw run
“`
—
막히는 문제
막히는 포인트는 대체로 정해져 있습니다. `PATH`/셸 캐시, 의존성, 보안 정책—이 셋이 대부분이에요.
주변에서 설치하다 포기한 사람도 꽤 봤는데, 대개 “내 잘못이 아닌데 내가 삽질하는 구간”에서 멈추더라고요.
Q&A로 빠르게 정리합니다.
- Q1. “명령을 찾을 수 없음”이 떠요
A.
- 설치 경로에 실행 파일이 있는지 확인 →
- `PATH`에 그 경로가 들어갔는지 확인 →
- 셸 캐시를 리셋합니다.
“`bash
which openclaw
echo “$PATH”
hash -r # bash 계열에서 캐시 갱신(zsh는 보통 rehash)
“`
- Q2. 의존성 오류(라이브러리/런타임/권한)는 뭘 먼저 봐야 해요?
A. 순서를 잡아두면 훨씬 빨라집니다.
– (
- 에러 메시지에 “missing / not found”가 뭘로 뜨는지(파일? 라이브러리?
런타임?)
– ( - 내 아키텍처(`arm64`/`x86_64`)와 설치된 의존성 아키텍처가 맞는지
– ( - 권한 문제라면 사용자 영역 설치로 옮길 수 있는지
Q3. macOS/리눅스 보안 정책 때문에 실행이 막혀요
A. macOS는 게이트키퍼/격리 속성 때문에 막히는 경우가 있고, 리눅스는 SELinux/AppArmor 같은 정책이 원인일 수 있습니다.
핵심은 “정책을 꺼버리기”가 아니라, 왜 막혔는지 로그로 확인하고 필요한 예외만 적용하는 거예요. – macOS: 격리 속성(`com.apple.quarantine`)이 원인일 수 있습니다.
– Linux: SELinux 환경이면 거부 로그를 먼저 확인합니다.
(여기서부터는 환경에 따라 위험도가 갈리니, 회사 PC/운영 서버라면 보안 담당 기준을 우선하세요.)
—
유지관리 팁
업데이트는 “호환성 확인 → 백업/핀 → 적용”이 기본이고, 제거는 “실행 파일 + 캐시 + 설정 파일” 범위를 정해두면 깔끔합니다.
처음엔 반신반의했는데, 2주만 지나도 차이가 나요. 환경이 안정되면 팀 커뮤니케이션 비용이 확 줄어듭니다.
– 업데이트 체크 포인트
– 설정 파일 포맷이 바뀌는지
– 플러그인/확장(있다면) 호환이 깨지지 않는지
– 실행 옵션/서브커맨드 이름이 바뀌지 않았는지
– 제거(정리 범위 합의)
– 실행 파일 제거(설치 방식에 따라 다름)
– 캐시 폴더(있다면) 삭제
– 설정 파일은 “완전 제거”인지 “재설치 대비 보관”인지 먼저 결정
– 롤백 전략
– 이전 버전 바이너리/패키지 버전을 한 번은 보관
– 팀이라면 “버전 핀 고정”을 문서로 남기기(누가 봐도 같은 환경 재현)
마지막으로 설치 기록을 한 줄로라도 남겨두면 좋습니다.
예를 들어 “OS/아키텍처/설치 방식/버전/특이사항” 5개만 적어두면, 다음 장애 대응 속도가 달라져요.
참고로 읽을거리(설치 자체와는 결이 다르지만, 환경 선택에 도움 됩니다. 링크/내용은 시점에 따라 바뀔 수 있어요):
– How-To Geek: `https://www.howtogeek.com/why-linux-is-the-best-place-to-learn-programming-and-coding/`
– How-To Geek: `https://www.howtogeek.com/powerful-windows-features-most-people-never-turn-on/`
– Product Hunt: `https://www.producthunt.com/products/lyria-3-by-google-deepmind`
—
> 한 줄만 기억하면 됩니다. `openclaw`는 “설치”보다 “검증 루틴”이 반입니다—버전/도움말 찍고, 작은 샘플 한 번, 로그 준비까지.