오픈 클로 설치하기, 그리고 안 될 때 볼 것들

오픈 클로(OpenClaw) 설치 자체는 몇 분이면 끝납니다. 시간을 잡아먹는 건 그다음입니다. 명령어를 못 찾는다거나, 설치는 됐는데 게이트웨이가 안 뜬다거나, 잘 돌던 맥이 한숨 자고 일어나더니 조용해지는 식이죠.

그 부분들을 미리 정리해뒀습니다.

오픈 클로가 뭔가

내 컴퓨터나 서버에서 직접 돌리는 게이트웨이입니다. 프로세스 하나를 띄워두면 그게 메신저 앱과 AI 에이전트 사이를 이어줍니다. 공식 문서 표현으로는 "세션·라우팅·채널 연결의 단일 진실 공급원"이고, 나머지(CLI, 웹 UI, 폰 앱)는 전부 이 게이트웨이한테 말을 겁니다.

그래서 이름 하나에 여러 조각이 딸려옵니다.

• CLI — openclaw …
• 데몬 — 맥은 launchd, 리눅스·WSL2는 systemd 유저 서비스, 윈도우는 작업 스케줄러
• 웹 관리 화면 — http://127.0.0.1:18789/
• 도커 이미지 — ghcr.io/openclaw/openclaw:latest
• 보조 앱 — 맥 메뉴바 앱, 윈도우 허브, iOS·안드로이드 노드

18789 포트는 기억해두세요. 아래 문제 해결 절반이 이 포트 얘기입니다.

설치 전에 확인할 것

노드 버전. 22.22.3 이상, 24.15 이상, 또는 25.9 이상이어야 합니다. 22.22.3 미만은 안 됩니다.

모델 API 키 하나. 온보딩 마법사가 물어보니 파일에 직접 넣을 필요는 없습니다. 앤트로픽, OpenAI, 구글, xAI, 베드락, 애저, Groq, 미스트랄, 딥시크, OpenRouter 등 지원 목록이 깁니다. Ollama·LM Studio·vLLM으로 로컬 모델도 되고, OpenAI나 앤트로픽 호환 엔드포인트면 대체로 붙습니다.

이미 쓰는 구독을 재활용할 수도 있습니다. 로그인된 Claude CLI(Pro/Max/Team/Enterprise), OpenAI Codex OAuth, 깃허브 코파일럿, Gemini CLI 전부요. 다만 문서가 짚어둔 게 있는데, 구독을 재활용하면 그 플랜의 사용 한도를 깎아먹습니다. 하루 종일 켜둘 거면 "앤트로픽 API 키 쪽이 비용 예측이 낫다"고 문서가 직접 권합니다.

pnpm은 소스로 빌드할 때만 필요합니다. 저장소 루트에서 그냥 npm install 하는 건 지원 안 하는 방식이라고 문서에 명시돼 있습니다. pnpm 워크스페이스라서요.

설치

설치 스크립트 (문서 권장)

OS를 알아서 감지하고, 노드가 없으면 같이 깔아줍니다.

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

윈도우는 파워셸에서:

iwr -useb https://openclaw.ai/install.ps1 | iex

온보딩 없이 설치만 하려면:

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

시스템 노드를 안 건드리고 싶다면

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

npm / pnpm / bun

npm install -g openclaw@latest
openclaw onboard --install-daemon

npm install -g openclaw@latest --allow-scripts openclaw

pnpm도 비슷합니다.

pnpm add -g --allow-build=openclaw openclaw@latest

소스에서

git clone https://github.com/openclaw/openclaw.git
cd openclaw
pnpm install && pnpm build && pnpm ui:build
pnpm link --global
openclaw onboard --install-daemon

제대로 됐는지 확인

openclaw --version
openclaw doctor
openclaw gateway status
openclaw dashboard

뭔가 이상하면 일단 openclaw doctor부터 돌리세요. 아래 문제 해결에 나오는 것들 상당수를 알아서 잡아냅니다.

도커로 설치

./scripts/docker/setup.sh

이미지는 ghcr.io/openclaw/openclaw:latest이고 도커 허브에도 openclaw/openclaw:latest로 미러가 있습니다. 베이스는 node:24-bookworm-slim, PID 1은 tini입니다. slim과 크로미움이 들어간 latest-browser 태그도 있습니다.

헬스 체크:

curl -fsS http://127.0.0.1:18789/healthz

텔레그램 연결하기

여기서 다들 한 번 놀랍니다. 코어에 기본으로 들어있는 채널은 iMessage, 텔레그램, 웹챗 셋뿐입니다. 왓츠앱, 디스코드, 슬랙, 시그널, 라인 같은 건 전부 별도 플러그인이고, 설치한 다음 게이트웨이를 재시작해야 합니다.

한국에서 쓸 거면 텔레그램이 가장 빠릅니다. 토큰 하나면 끝나고 QR 절차가 없어서요.

@BotFather에게 /newbot을 보내고 토큰을 받으세요.

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing",
      groups: { "*": { requireMention: true } },
    },
  },
}

openclaw gateway
openclaw pairing list telegram
openclaw pairing approve telegram <코드>

왓츠앱은 단계가 둘입니다

openclaw plugins install clawhub:@openclaw/whatsapp
openclaw channels login --channel whatsapp
openclaw pairing approve whatsapp <코드>

로그인은 QR만 됩니다. Baileys, 즉 왓츠앱 웹 방식이라서요.

헷갈리기 쉬운 부분: QR 로그인과 페어링 승인은 서로 다른 관문입니다. QR은 내 왓츠앱 계정을 게이트웨이에 붙이는 거고, 페어링 승인은 어떤 사람이 에이전트한테 말을 걸 수 있는지 정하는 겁니다. 앞엣것을 했다고 뒤엣것이 되지 않습니다.

설정 파일

~/.openclaw/openclaw.json이고 포맷은 JSON5입니다. 주석이랑 트레일링 콤마가 되고 키에 따옴표를 안 써도 됩니다.

{
  agents: { defaults: { model: { primary: "anthropic/claude-opus-4-6" } } },
}

위치는 OPENCLAW_HOME, OPENCLAW_STATE_DIR, OPENCLAW_CONFIG_PATH로 옮길 수 있습니다.

API 키는 이 파일에 그냥 박아두지 마세요. 문서에도 명시돼 있습니다. 온보딩 마법사를 쓰면 별도 인증 파일에 들어갑니다.

메모리는 그냥 파일입니다

에이전트 기억은 워크스페이스 안의 마크다운 파일들이고, 새 세션 첫 턴에 프로젝트 컨텍스트로 주입됩니다.

• AGENTS.md — 운영 지침 겸 메모리
• SOUL.md — 성격
• IDENTITY.md, USER.md
• MEMORY.md — 장기 기억. 단 워크스페이스 루트에 있을 때만 동작합니다
• BOOTSTRAP.md — 최초 한 번 실행되고 스스로 지워집니다

안 될 때

openclaw: command not found

문서 표현이 단호합니다. "거의 항상 PATH 문제." npm 전역 bin이 PATH에 없는 겁니다.

npm config get prefix

거기 bin을 PATH에 넣으세요. 윈도우는 보통 %AppData%\npm입니다.

설치는 됐는데 게이트웨이가 안 뜬다

bun으로 설치하셨다면 그게 원인입니다. node:sqlite가 없어서요. 노드로 다시 설치하세요.

EADDRINUSE가 뜨거나 게이트웨이가 계속 재시작된다

18789 포트를 뭔가 다른 게 쓰고 있거나, 서비스 정의가 두 개입니다. launchd 잡이나 systemd 유닛이 중복된 경우인데, 설치 방법을 바꿔가며 두 번 설치하면 잘 생깁니다. 둘 다 확인하세요.

업데이트했더니 채널이 사라졌다

plugin load failed: dependency tree corrupted; run openclaw doctor --fix

적힌 그대로 실행하면 됩니다.

서비스 제어 명령이 먹통이다

설치가 둘로 갈린 상태입니다. PATH에 남아있는 옛날 바이너리가 새 설정을 건드리고 있는 거예요. 오래된 쪽을 찾아 지우세요.

맥에서 한참 뒤에 아무 말 없이 멈춘다

이게 제일 골치입니다. 에러가 안 나거든요. Power Nap이나 유지관리 절전 중에 와이파이가 끊겼다 붙는데, launchd 재시작 게이트에 걸려서 안 돌아오는 겁니다. 세 개를 같이 해야 잡힙니다.

• 2026.5.26보다 높은 버전으로 올리기
• sudo pmset -a sleep 0 disksleep 0 standby 0 powernap 0
• 외부 워치독 걸어두기 — 침묵 말고 다른 걸로 알아챌 수 있게

도커 빌드가 exit 137로 죽는다

메모리 부족입니다. 2GB 이상인 데서 빌드하세요.

세션이 커지면서 메모리 경고가 뜬다

critical memory pressure bundle written이 보이면 세션 기록(.jsonl)이 커진 겁니다. 오래된 세션을 정리하세요.

라즈베리파이

파이 5, 또는 램 2GB 이상인 파이 4에 64비트 OS를 쓰세요. 파이 제로 2 W(512MB)는 권장하지 않는다고 문서에 적혀 있습니다.

보안 기본값

오픈 클로 문서는 이 부분을 꽤 솔직하게 써뒀습니다. 뭔가를 외부에 열기 전에 읽어볼 값어치가 있습니다.

게이트웨이는 신뢰할 수 있는 운영자 한 명을 전제합니다. 문서 표현을 그대로 옮기면 "여러 적대적 사용자가 하나의 에이전트나 게이트웨이를 공유하는 상황에 대한 보안 경계가 아니다"입니다. 여러 사람한테 게이트웨이 하나를 열어줄 생각이었다면, 그건 설계 범위 밖입니다.

프롬프트 인젝션은 아직 해결 안 된 문제로 명시돼 있습니다. 시스템 프롬프트 가드레일은 "약한 지침일 뿐이고, 실제 강제는 도구 정책·실행 승인·샌드박싱·채널 허용목록에서 나온다"고 적혀 있고요. 그리고 "위협은 발신자만이 아니라 내용 자체"라는 문장이 있습니다. 에이전트가 읽는 웹페이지, 메일, 첨부파일 전부 해당합니다.

기본값은 보수적으로 잡혀 있으니 그대로 두세요. dmPolicy: "pairing"이면 모르는 사람이 보낸 메시지는 처리되지 않고 페어링 코드만 나갑니다. 코드는 한 시간 뒤 만료되고요. 열어두는 건 일부러 번거롭게 만들어놨습니다 — dmPolicy: "open"으로 바꾸고 허용목록에 "*"를 넣는 것까지 둘 다 해야 합니다.

문서가 하지 말라고 적어둔 것들: 인증 없이 0.0.0.0에 바인딩, allowedOrigins: ["*"], 평소 쓰는 브라우저 프로필을 브라우저 제어에 연결, 홈 디렉토리를 워크스페이스 루트로 지정. 플러그인은 같은 프로세스 안에서 돌고 신뢰된 코드로 취급되니, 설치는 편의가 아니라 결정입니다.

openclaw security audit --deep

깃허브 저장소에 공개 보안 권고 목록도 있습니다. 깁니다. 프로젝트가 워낙 빨리 움직이고 주목을 많이 받아서이기도 하지만, 뭘 연결할지 정하기 전에 한 번 보세요.

출처

이 글의 내용은 전부 오픈 클로 공식 문서와 깃허브 저장소에서 가져왔고, 2026년 7월 30일에 v2026.7.1 기준으로 확인했습니다. 공식 소스끼리 어긋나는 부분(권장 노드 버전 등)은 한쪽을 고르지 않고 그렇다고 적었습니다.

• docs.openclaw.ai/install
• docs.openclaw.ai/channels
• docs.openclaw.ai/gateway/troubleshooting
• docs.openclaw.ai/gateway/security
• github.com/openclaw/openclaw

오픈 클로 프로젝트와는 아무 관계가 없습니다. 틀린 내용이나 오래된 부분이 있으면 알려주세요. 고치겠습니다.