OpenClaw 설치부터 텔레그램 연결까지 — 30분 실전 셋업 가이드

안녕하세요, 자바파커입니다.

"OpenClaw가 뭔지는 알겠는데... 그래서 이거 어떻게 깔아요?"

지난 편에서 OpenClaw가 뭔지, 왜 5개월 만에 GitHub 최다 스타가 됐는지를 정리했더니 딱 이 질문이 돌아왔습니다. 소개만 보면 근사한데, 막상 설치하려면 데몬이니 Gateway니 낯선 단어부터 막히죠.

결론부터 말씀드리면 — 설치 자체는 명령 몇 줄이면 끝납니다. 진짜 핵심은 (1) 공식 출처에서 받고, (2) onboard 마법사로 두뇌(LLM)를 연결하고, (3) 메신저 하나를 페어링하는 흐름입니다. 이 글에서는 텔레그램 봇으로 실제 대화가 오갈 때까지를 4단계로, 순서대로 따라 하실 수 있게 정리했습니다. 넉넉잡아 30분이면 됩니다.

이 글은 OpenClaw 파헤치기 시리즈의 두 번째, 설치·연결 실전편입니다. OpenClaw가 처음이라면 소개 편을 먼저 읽고 오시길 권합니다.

전체 그림 — 4단계 셋업 흐름

한 문장으로 요약하면 — 깔고(1), 두뇌 붙이고(2), 살아있나 확인하고(3), 메신저 연결(4) 입니다.

0단계: 설치 전 체크리스트

본격적으로 깔기 전에 딱 세 가지만 확인하세요.

① Node.js 버전 — OpenClaw는 최신 Node를 요구합니다. 권장은 Node 24.15+ 이고, 22.22.3+ 또는 25.9+ 도 동작합니다. 터미널에서 확인:

node -v
# v24.15.0 처럼 나오면 OK. 낮으면 nvm/fnm 등으로 업그레이드

② LLM 연결 수단 (API 키 또는 구독) — OpenClaw는 두뇌가 없습니다. Claude·GPT 같은 외부 LLM을 손발처럼 부리는 껍데기죠. 그래서 두뇌를 연결할 인증 수단이 하나 필요한데, 방법은 두 가지입니다.

• API 키 — Anthropic·OpenAI 등에서 발급한 키를 넣는 방식. 쓴 만큼 종량제로 과금됩니다.
• 구독 계정 로그인 — 이미 Claude Pro/Max나 ChatGPT Plus/Pro 같은 월 구독을 쓰고 있다면, 별도 API 키 없이 그 구독 계정으로 로그인해 연결할 수 있습니다. 매달 정액만 내고 쓰는 분에게 유리하죠.

어느 쪽이든 사용량·약관은 해당 서비스 정책을 따릅니다. 구독 로그인은 구독 플랜의 사용 한도(rate limit) 안에서 동작하고, API 키는 쓴 만큼 청구됩니다. 가볍게 감을 잡을 땐 이미 있는 구독으로 시작하고, 자동화를 많이 돌릴 계획이면 API 키 종량제를 저울질해 보세요.

③ 공식 출처 재확인 — 지난 편에서 강조했듯, OpenClaw는 사칭·타이포스쿼트 배포가 특히 많은 프로젝트입니다. 설치 주소는 아래 두 곳만 신뢰하세요. 한 글자씩 확인하는 습관이 최고의 보안입니다.

• 공식 사이트: openclaw.ai
• 공식 레포: github.com/openclaw/openclaw

보안 배경(가짜 npm 패키지, 악성 복제 레포, 공급망 공격)이 왜 이렇게 심각한지는 소개 편의 보안 섹션에서 자세히 다뤘습니다.

1단계: OpenClaw 설치하기

공식 권장 방식은 설치 스크립트 한 줄입니다. OS에 맞춰 고르세요.

macOS / Linux

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

Windows (PowerShell)

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

npm으로 직접 설치(대안) — 이미 Node 환경이 잡혀 있다면 npm 전역 설치도 됩니다.

npm install -g openclaw@latest

⚠️ curl ... | bash, iwr ... | iex는 받은 스크립트를 그대로 실행하는 방식입니다. 편하지만, 주소가 진짜 openclaw.ai가 맞는지 반드시 눈으로 확인하세요. 찜찜하면 스크립트를 파일로 먼저 내려받아(curl -fsSL https://openclaw.ai/install.sh -o install.sh) 열어본 뒤 실행하는 것도 방법입니다.

설치가 끝났으면 버전으로 확인:

openclaw --version

2단계: onboard — 두뇌 연결 + 데몬 등록

설치했다고 바로 쓰는 게 아닙니다. onboard 마법사를 돌려야 두뇌(LLM)를 연결하고 Gateway를 상시 실행 상태로 만들 수 있습니다.

openclaw onboard --install-daemon

이 한 줄이 대화형 마법사를 띄우고, 순서대로 물어봅니다.

1. 모델 제공자 선택 — Claude(Anthropic), GPT(OpenAI) 등
2. 인증 방식 선택 — 준비한 API 키를 붙여넣거나, Claude·ChatGPT 구독 계정으로 로그인(별도 키 불필요)
3. 워크스페이스 설정 — 에이전트가 파일을 읽고 쓸 작업 폴더
4. Gateway 데몬 등록 — --install-daemon 덕분에 macOS는 launchd, Linux는 systemd 사용자 서비스로 등록되어, 재부팅 후에도 백그라운드에서 항상 떠 있게 됩니다.

여기서 등장하는 Gateway가 OpenClaw의 심장입니다. 세션·채널·툴·이벤트를 내 기기 안에서 관리하는 로컬 컨트롤 플레인이죠(로컬 우선 설계의 핵심). onboard가 이 데몬을 "항상 켜진 상태"로 만들어 줍니다.

3단계: Gateway 살아있는지 확인 + Control UI

데몬이 제대로 떴는지 상태부터 봅니다.

openclaw gateway status

정상이라면 Gateway가 포트 18789에서 리스닝 중이라고 나옵니다. 안 뜨거나 죽어 있으면 재시작:

openclaw gateway restart

이제 브라우저 대시보드(Control UI)를 열어 실제로 대화가 되는지 확인합니다.

openclaw dashboard

브라우저가 열리면 채팅창에 아무 말이나 입력해 보세요. AI 응답이 돌아오면 두뇌 연결까지 성공입니다. 여기까지 오면 OpenClaw 본체는 완성이고, 남은 건 "어떤 메신저로 부릴 것인가"뿐입니다.

4단계: 텔레그램 봇 연결하기 (가장 빠른 채널)

OpenClaw는 29개 채널을 지원하지만, 가장 손쉬운 건 텔레그램입니다. 봇 토큰 하나면 끝나거든요.

① BotFather로 봇 토큰 발급

1. 텔레그램에서 @BotFather 검색 (파란 인증 체크마크 확인 — 사칭 봇 주의)
2. 대화창에서 /newbot 전송
3. 봇 이름과 사용자명을 프롬프트에 따라 입력
4. 발급된 토큰 문자열을 복사 (123456:ABC-DEF... 형태)

② 토큰을 OpenClaw에 등록

설정 파일(JSON5)에 채널을 추가하거나:

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "여기에_발급받은_토큰",
      dmPolicy: "pairing",   // 아무나 말 걸지 못하게 페어링 방식 권장
    },
  },
}

또는 환경 변수로 간단히 넣어도 됩니다.

export TELEGRAM_BOT_TOKEN="여기에_발급받은_토큰"

③ Gateway 재기동 + 페어링 승인

토큰을 넣었으면 Gateway를 띄우고, 내 계정을 봇과 페어링해서 연결합니다.

openclaw gateway
openclaw pairing list telegram          # 대기 중인 페어링 코드 확인
openclaw pairing approve telegram <CODE> # 그 코드를 승인

페어링 코드는 발급 후 1시간 뒤 만료됩니다. 목록에서 코드가 안 보이면, 텔레그램에서 내 봇에게 먼저 메시지를 한 번 보내 페어링 요청을 만들어 주세요.

승인이 끝나면, 이제 텔레그램에서 내 봇에게 문자를 보내듯 지시하면 됩니다. "이 폴더 로그 정리해줘", "매일 아침 요약 보내줘" 처럼요. 메신저가 곧 AI 비서의 리모컨이 되는 순간입니다.

자주 막히는 지점 — 트러블슈팅

문제가 생기면 "어디까지 됐나"를 3·4단계 순서로 되짚는 게 가장 빠릅니다. Gateway(3단계)가 살아있고 Control UI에서 AI 응답이 되면, 남은 문제는 대부분 채널(4단계) 설정입니다.

자주 묻는 질문 (FAQ)

Q. 설치하는 데 돈이 드나요? OpenClaw 자체는 MIT 오픈소스라 무료입니다. 비용은 두뇌로 쓰는 LLM 쪽에서 발생하는데, 연결 방식에 따라 다릅니다. API 키를 쓰면 쓴 만큼 종량제로 청구되고, 이미 Claude Pro/Max·ChatGPT Plus/Pro 같은 월 구독이 있다면 그 계정으로 로그인해 추가 API 비용 없이 구독 한도 안에서 쓸 수 있습니다. 가볍게 시작할 땐 기존 구독을, 자동화를 많이 돌릴 땐 API 키 종량제를 저울질하세요.

Q. Windows에서도 잘 되나요? 네. PowerShell 설치 스크립트(install.ps1)가 제공되고, 컴패니언 앱도 Windows를 지원합니다. 다만 데몬 등록(자동 상시 실행) 방식은 OS마다 조금씩 달라, 재부팅 후 상태 확인(gateway status)을 한 번 해두면 안심입니다.

Q. 텔레그램 말고 다른 메신저도 되나요? 됩니다. 디스코드·슬랙·왓츠앱·시그널·iMessage 등 29개 채널을 지원합니다. 다만 초기 세팅 난이도가 가장 낮은 게 텔레그램(봇 토큰 하나)이라 첫 연결로 추천합니다. 익숙해진 뒤 다른 채널을 추가하세요.

Q. curl | bash 설치가 불안한데 괜찮나요? 편의성과 보안의 트레이드오프입니다. 주소가 공식 도메인(openclaw.ai)이 맞는지만 확실하면 위험은 크게 줄어듭니다. 더 안전하게 가려면 스크립트를 파일로 내려받아 내용을 확인한 뒤 실행하거나, npm 전역 설치를 쓰세요.

마무리 — 다음 편 예고

여기까지 따라오셨다면, 이제 텔레그램 한 줄로 내 컴퓨터의 AI 비서를 부리는 상태가 됐습니다. 설치(1) → 두뇌 연결(2) → 상태 확인(3) → 메신저 페어링(4), 이 흐름만 손에 익으면 다른 채널을 붙이는 것도 금방입니다.

다음 편에서는 한 발 더 나아가, ClawHub 스킬을 설치해 실제로 일을 시키는 실전 활용법을 다룹니다. "매일 아침 요약", "웹에서 데이터 긁어오기" 같은 자동화를 스킬 단위로 등록하는 방법이죠.

메신저로 AI 코딩 에이전트를 원격 조종하는 흐름이 궁금하다면, 텔레그램에서 Claude Code를 부리는 COKACDIR 이야기도 결이 비슷하니 함께 읽어보시길 권합니다.

참고 자료

설치·설정 절차는 아래 공식 문서를 기준으로 정리했습니다. 버전에 따라 명령·옵션이 바뀔 수 있으니, 실제 설치 시엔 공식 문서를 함께 확인하세요.

• 공식 시작 가이드 — docs.openclaw.ai/start/getting-started
• 텔레그램 채널 문서 — docs.openclaw.ai/channels/telegram
• 공식 저장소 — github.com/openclaw/openclaw
• npm 패키지 — npmjs.com/package/openclaw

OpenClaw는 빠르게 개발 중인 프로젝트라 명령·포트·옵션이 업데이트될 수 있습니다. 본문은 2026년 7월 기준이며, 최신 절차는 공식 문서에서 확인하세요.

설치하면서 어느 단계에서 가장 막히셨나요? Gateway 데몬 등록인가요, 아니면 텔레그램 페어링인가요? 막힌 지점을 댓글로 남겨주시면, 다음 실전편에서 함께 짚어보겠습니다. 🦞