OpenClaw: 무엇이며, 설치하고 Telegram에 연결하는 방법

지난겨울, 프로젝트가 일주일 사이에 이름을 두 번 바꾸고 GitHub에서 수십만 개의 별을 얻었을 때 OpenClaw가 제 피드에 등장했습니다. 그 이후로 “openclaw 설치”와 “openclaw telegram”을 검색하는 사람이 점점 늘고 있습니다.

아래에서는 공식 문서를 살펴보며 이 도구가 무엇인지, Claude Code와 어떻게 다른지, Windows, macOS 또는 Linux에 설치하는 방법, 모델을 선택하고 Telegram 봇을 연결하는 방법을 설명합니다. OpenClaw가 몇 차례 세간의 주목을 받은 보안 사고에 연루된 적이 있어 보안도 별도 항목으로 다룹니다.

서비스 사용법은 Ailoot 문서에서 알아보세요.

OpenClaw란 무엇인가요? 쉽게 설명하면#

OpenClaw는 AI 모델을 Telegram 봇에 연결합니다. 필요한 도구와 권한을 설정하면 메시지 요약이나 알림 예약을 할 수 있습니다. 게이트웨이 프로세스와 로컬 설정은 자신의 컴퓨터나 서버에서 실행됩니다. 그렇다고 모든 대화가 로컬에 머무는 것은 아닙니다. 클라우드 모델을 선택하면 요청과 관련 대화 컨텍스트가 해당 공급자에게 전송됩니다. Ailoot으로 연결하면 요청이 Ailoot을 거쳐 선택한 모델 공급자에게 전달됩니다. 로컬 추론에는 로컬 모델과 클라우드 대체 경로 비활성화가 필요합니다. 그래도 Telegram 메시지는 Telegram을 통과하고, 활성화한 도구는 다른 서비스에 접속할 수 있습니다.

이 프로젝트는 OpenClaw 오픈 소스 커뮤니티가 개발합니다. GitHub 저장소는 2025년 11월 24일에 만들어졌으며, 2026년 8월 22일 현재 별 38만 7천 개와 포크 8만 1천 개를 기록했습니다. 그해 가장 빠르게 성장한 오픈 프로젝트 중 하나입니다. 사용된 언어는 TypeScript입니다.

프로젝트 이름의 역사가 재미있는데, 오래된 글을 읽을 때 혼동하지 않으려면 알아둘 만합니다. 처음에는 WhatsApp용 게이트웨이인 Warelay로 시작했습니다. 이후 Clawdbot이 되었습니다. 2026년 1월, Anthropic이 상표 문제로 이름을 바꿔 달라고 요청하면서 프로젝트는 며칠 동안 Moltbot이라는 이름을 썼습니다. 2026년 1월 30일에 최종 이름인 OpenClaw를 얻었습니다. 따라서 “Clawdbot”이나 “Moltbot”에 관한 안내를 발견해도 같은 프로젝트입니다. 이름을 바꾸기 전에 작성된 글일 뿐입니다.

프로젝트의 마스코트는 Molty라는 랍스터이며, “탈피”(껍데기를 바꾸는 것)는 이름을 바꿀 때마다 쓰는 공식 비유가 되었습니다.

OpenClaw는 Claude Code 및 Hermes Agent와 어떻게 다른가요?#

겉으로 보기에는 모두 “AI 에이전트”처럼 보여서 이 차이에 관한 질문을 자주 받습니다. 비교표를 살펴보세요.

표를 읽는 방법은 이렇습니다. 저는 개발에 Claude Code를 씁니다. 강력한 모델이 필요하고 코드 작업을 할 때 가장 유용합니다. OpenClaw와 Hermes는 다른 목적에 맞습니다. 항상 실행되며 Telegram에 머무르고, 어제 나눈 대화를 기억하고, 일정에 따라 작업을 처리하는 에이전트입니다. OpenClaw와 Hermes 중 선택하는 일은 조금 더 미묘합니다. 설치 및 설정 방법을 다룬 Hermes 가이드가 이미 있습니다.

도구를 고르는 중이라면 개요부터 살펴보세요. 2026년에 사람들이 코딩할 때 쓰는 도구와 AI 에이전트에 맡길 수 있는 작업을 읽어보세요. Claude Code 설치 방법을 다룬 별도 글도 있습니다.

OpenClaw를 설치하기 전에 무엇이 필요한가요?#

Node 버전을 미리 확인하세요. 엄격한 필수 조건은 이것뿐입니다.

node --version

22.22.3+, 24.15+, 25.9+ 버전을 지원하며 Node 26을 권장합니다. 명령을 실행했을 때 “command not found”가 나오거나 버전이 오래된 경우에도 걱정하지 마세요. 공식 설치 프로그램이 최신 Node 버전을 다운로드하므로 직접 설치할 필요가 없습니다.

남은 것은 모델 선택입니다. OpenClaw는 스스로 사고하지 않습니다. 선택한 모델을 호출합니다. 비용에 따른 선택지는 다음과 같습니다. Anthropic, OpenAI 또는 Google 키를 사용하면 실제 사용량에 따라 공급자에게 비용을 지불합니다. Ollama를 통해 로컬 모델을 사용하면 비용은 들지 않지만 성능이 좋은 하드웨어가 필요합니다. 아래에서 두 옵션을 각각 별도의 섹션으로 다룹니다.

macOS와 Linux에 OpenClaw를 설치하는 방법#

권장 방법은 공식 설치 프로그램을 사용하는 것입니다.

1. 설치 프로그램 실행

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

   스크립트가 운영 체제를 감지하고 Node를 확인한 다음(필요하면 설치), OpenClaw를 설치하고 설정 마법사를 엽니다. 마법사를 실행하기 전에 먼저 살펴보고 싶다면 bash -s -- --no-onboard 플래그를 추가하세요.

2. 설치 확인

   openclaw --version
   openclaw doctor
   openclaw gateway status
   

   첫 번째 명령은 버전을 표시하고, 두 번째는 구성을 확인하며, 세 번째는 게이트웨이가 실행 중이고 포트 18789에서 대기하고 있는지 확인합니다.

npm을 사용하며 설치를 직접 관리하고 싶다면 다음을 실행하세요.

npm install -g openclaw@latest --allow-scripts=openclaw
openclaw onboard --install-daemon

최근 문서의 별도 장에서 다루는 주의 사항이 있습니다. npm 12는 기본적으로 패키지 설치 스크립트를 차단합니다. --allow-scripts=openclaw 플래그가 없으면 allowScripts 메시지와 함께 설치가 중단됩니다. npm 11.15 이하에서는 아직 그런 제한이 없으므로 플래그가 필요하지 않습니다. npm --version으로 버전을 확인하세요.

두 번째 명령의 --install-daemon 플래그는 자동 시작을 설정합니다. macOS에서는 LaunchAgent, Linux에서는 systemd 서비스로 등록됩니다. 서비스 관리자의 조건에 따라 재부팅이나 로그인 후 게이트웨이가 시작됩니다. 잠자기를 막거나 꺼진 컴퓨터에서 실행을 유지하지는 않습니다. Telegram 응답에는 깨어 있고 네트워크에 연결된 호스트가 필요합니다. 노트북이 잠들거나 꺼져도 응답하려면 상시 서버를 사용하세요.

Windows에 OpenClaw를 설치하는 방법#

첫 번째 방법은 터미널보다 창을 사용하는 편이 좋은 사람에게 적합합니다. Windows Hub는 Windows 10(20H2+) 및 Windows 11용 네이티브 OpenClaw 앱으로 현재 베타 버전입니다. Windows Hub 릴리스 페이지로 이동해 프로세서에 맞는 설치 프로그램을 다운로드하세요. 일반 컴퓨터에는 OpenClawCompanion-Setup-x64.exe, ARM에는 arm64를 사용합니다. 설치하면 시스템 트레이 아이콘, 채팅 창, 설정이 포함된 OpenClaw Companion이 시작 메뉴에 표시됩니다.

처음 실행할 때 앱에서 “Set up locally”를 제안하면 수락하세요. OpenClawGateway라는 전용 WSL 환경을 만들고 그 안에 게이트웨이를 설치한 뒤 연결합니다. 기존 Ubuntu 설치가 있더라도 건드리지 않습니다.

두 번째 방법은 PowerShell을 사용하는 것입니다.

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

첫 번째 줄은 OpenClaw를 설치하고, 두 번째 줄은 Windows 작업 스케줄러를 통해 자동 시작을 등록합니다. 컴퓨터 정책상 작업 생성이 차단되어 있으면 OpenClaw가 자동으로 대체 방법을 사용합니다. 시작 폴더에 바로가기를 넣어 로그인할 때 게이트웨이가 시작되도록 합니다.

세 번째 방법은 WSL2입니다. 문서에서는 이를 Windows에서 가장 호환성이 높은 실행 환경이라고 설명합니다. Ubuntu를 설치하고 systemd를 활성화한 뒤, 이전 섹션의 Linux 안내를 따르세요.

wsl --install -d Ubuntu-24.04

WSL 내부의 /etc/wsl.conf에서 systemd를 활성화하세요([boot] 섹션의 systemd=true 줄). PowerShell에서 wsl --shutdown을 실행해 WSL을 다시 시작한 다음 Linux 명령으로 OpenClaw를 설치합니다. “배포판”과 “systemd”가 무슨 뜻인지 모르겠다면 Windows Hub를 사용하세요. 이 모든 과정을 대신 처리해 줍니다.

모델을 선택하고 초기 설정을 완료하는 방법#

모델은 어시스턴트의 엔진입니다. 설정 마법사에서 공급자 목록이 표시됩니다. 실용적인 옵션 세 가지는 다음과 같습니다.

Anthropic에는 유용한 점이 있습니다. Claude Code가 이미 설치되어 로그인한 상태라면 OpenClaw가 그 로그인을 사용할 수 있습니다. 먼저 기기에서 claude auth login을 실행한 다음 OpenClaw에 해당 로그인을 사용하도록 지정하세요.

openclaw models auth login --provider anthropic --method cli --set-default

게이트웨이가 백그라운드 서비스로 실행된다면(--install-daemon을 사용한 경우처럼) 서비스가 키에 접근할 수 있어야 합니다. 키를 ~/.openclaw/.env에 넣으면 됩니다. 마법사가 처리하므로 파일을 직접 수정할 필요는 없습니다. 변경 후에는 재시작하고 확인하세요.

openclaw gateway restart
openclaw models status

비용 지불이 부담스럽다면 Ollama 섹션에서 설명하는 로컬 모델을 사용하면 됩니다.

OpenClaw를 Telegram에 연결하는 방법#

Telegram은 연결하기 가장 빠른 채널입니다. 봇 토큰만 있으면 되며 비즈니스 계정 인증은 필요하지 않습니다. 문서에서는 휴대폰으로 어시스턴트와 메시지를 주고받기 시작하는 가장 쉬운 방법이라고 설명합니다. 전체 과정은 다음과 같습니다.

1. BotFather로 봇 만들기

   Telegram에서 @BotFather와 채팅을 열고(정확히 이 사용자 이름인지 확인하세요. 가짜가 많습니다) /newbot을 보낸 다음 이름과 bot으로 끝나는 사용자 이름을 선택합니다. 응답으로 123456789:ABCdef... 같은 토큰을 받습니다. 봇의 키이므로 비밀번호처럼 보관하세요.

2. OpenClaw에 토큰 입력

   가장 쉬운 방법은 마법사를 사용하는 것입니다. openclaw configure를 실행하고 Telegram 채널을 선택하세요. 직접 설정하려면 channels.telegram.botToken 설정이나 TELEGRAM_BOT_TOKEN 환경 변수를 사용할 수 있습니다. 문서에는 openclaw channels login telegram 명령이 존재하지 않으며 Telegram은 토큰으로만 연결된다고 명시되어 있습니다.

3. 게이트웨이를 시작하고 봇에 메시지 보내기

   openclaw gateway
   

   Telegram에서 봇을 열고 메시지를 보내세요. 봇은 8자리 페어링 코드로 답변합니다. 발신자를 승인하기 전에는 메시지가 처리되지 않도록 하는 보안 장치입니다.

4. 본인 승인

   openclaw pairing list telegram
   openclaw pairing approve telegram CODE
   

   코드는 한 시간 동안 유효하므로 너무 오래 기다리지 마세요. 처음 승인된 발신자가 자동으로 권한 명령의 소유자가 됩니다.

사람들이 자주 마주치는 까다로운 점이 두 가지 있습니다.

첫 번째는 그룹입니다. OpenClaw는 기본적으로 모든 그룹을 차단합니다. channels.telegram.groups 설정에서 봇을 명시적으로 허용하고 그룹에서 requireMention: true 모드를 계속 활성화해야 합니다. 그러면 사용자 이름으로 호출될 때만 답변하고 일반 대화에 끼어들지 않습니다. Telegram에는 자체 봇 개인정보 보호 모드도 있습니다. 그룹에서 기본적으로 봇은 명령만 볼 수 있습니다. @BotFather에서 /setprivacy를 사용해 이 기능을 끄세요. 설정을 변경한 다음에는 봇을 그룹에서 내보냈다가 다시 추가해야 적용됩니다.

두 번째는 모든 사람에게 접근 권한을 열지 않는 것입니다. 설정에는 접근 목록에 별표가 붙는 dmPolicy: "open" 모드가 있습니다. 이 모드에서는 사용자 이름만 아는 사람이라면 누구나 봇에 명령을 내릴 수 있습니다. 개인용 어시스턴트에서 이는 다른 사람이 내 컴퓨터를 제어하게 하는 직접적인 통로입니다. 코드 페어링을 활성화해 두거나 allowFrom에 숫자 ID를 입력하세요.

Ollama를 통해 로컬 모델로 OpenClaw를 실행하는 방법#

클라우드 대체 경로가 없는 로컬 전용 경로를 선택하면 모델 추론은 자신의 하드웨어에서 처리하며 유료 모델 엔드포인트가 필요하지 않습니다. 그렇다고 Telegram 작업 전체가 로컬인 것은 아닙니다. 메시지는 Telegram을 통과하고 활성화한 온라인 도구는 다른 서비스로 데이터를 보낼 수 있습니다.

1. Ollama 설치

   ollama.com/download에서 설치 프로그램을 다운로드하세요. macOS, Windows, Linux용 버전이 있습니다.

2. 모델 다운로드

   ollama pull gemma4
   

3. Ollama를 OpenClaw에 연결

   openclaw onboard
   

   Ollama 공급자와 모드를 선택합니다. Local only(내 모델만), Cloud only(ollama.com의 모델만) 또는 Cloud + Local입니다. 마법사가 로컬 서버를 찾고 설치된 모델을 표시합니다.

4. 확인

   openclaw models list --provider ollama
   

이 섹션이 광고처럼 읽히지 않도록 솔직한 단서를 덧붙이겠습니다. OpenClaw 문서에 따르면 로컬 모델로 에이전트를 편하게 사용하려면 Mac Studio 두 대를 최대 성능으로 구동하는 수준의 하드웨어가 필요합니다. 24 GB 그래픽 카드로는 지연이 발생하면서 가벼운 요청만 처리할 수 있습니다. 작고 많이 압축된 모델은 컨텍스트를 잘라내고 다른 사람의 텍스트에 숨겨진 악의적인 지시에 덜 잘 대응합니다. 쉽게 말해, 좋은 노트북의 로컬 모델은 “써 보고 어떤 것인지 알아보기”에는 충분하지만, 도구를 사용하는 어시스턴트의 일상적인 작업에는 클라우드 모델이 여전히 훨씬 안정적입니다.

WSL2 + Ollama + NVIDIA GPU를 설정하는 분들을 위해 문서에서 전하는 주의 사항이 하나 더 있습니다. 공식 Linux Ollama 설치 프로그램은 “always” 재시작 정책으로 자동 시작을 활성화합니다. GPU를 사용하는 WSL2에서는 이 설정 때문에 컴퓨터가 재시작을 반복할 수 있습니다. 서비스 자동 시작을 비활성화하면 해결됩니다. 문제가 발생하면 문서의 Ollama 페이지에서 문제 해결 섹션을 확인하세요.

OpenClaw 실행은 얼마나 안전한가요?#

먼저 모두가 이해하는 것은 아닌 핵심부터 말하겠습니다. OpenClaw는 내 기기의 파일, 명령, 브라우저에 접근할 수 있습니다. 문서도 분명하게 설명합니다. 이 프로젝트는 신뢰할 수 있는 사용자 한 명을 위해 설계되었으므로 외부인에게 봇 접근 권한을 주면 안 됩니다. 누군가 내 에이전트에 메시지를 보낼 수 있다면 내 컴퓨터에서 작업을 실행하는 데 이용할 수 있습니다.

기본적인 안전 수칙은 다음과 같습니다.

1. 코드 페어링을 활성화해 두거나 접근 목록을 사용하세요. Telegram 섹션에서 설정 방법을 설명했습니다.
2. 필요하지 않다면 게이트웨이를 외부에 노출하지 마세요. 기본값은 내 기기에서만 대기하는 것입니다. 그대로 두세요.
3. 구성을 변경한 후에는 내장 검사를 실행하세요.

openclaw security audit

이 검사는 공개된 접근 권한, 지나치게 넓은 도구 권한, 약한 토큰, 노출된 포트를 확인합니다. --fix 플래그를 사용하면 일부 항목을 자동으로 수정할 수 있습니다.

사기에 관한 별도 안내입니다. 이는 가상적인 위험이 아닙니다. 2026년 1월 프로젝트가 급하게 이름을 바꾸자, 스쿼터 봇이 몇 초 만에 이전 주소를 차지하고 곧바로 암호화폐 지갑 주소를 게시했습니다. 가짜 “OpenClaw 개발자”들이 토큰 사기를 홍보하기 시작했습니다. 여기서 꼭 기억해야 할 규칙 두 가지가 나옵니다. openclaw.ai 또는 github.com/openclaw/openclaw에서만 OpenClaw를 다운로드하세요. 그리고 프로젝트에는 암호화폐가 없습니다. “OpenClaw 토큰”은 모두 사기입니다. 어떤 경우에도 돈을 보내지 마세요.

설치 후 OpenClaw로 무엇을 할 수 있나요?#

다음 순서로 시도해 보세요.

1. 게이트웨이와 모델. openclaw gateway status를 실행한 뒤 openclaw dashboard를 여세요. 패널이 로드되면 Control UI에 접속할 수 있음을 확인한 것입니다. 채팅에 “model connection test라고 답하세요”를 보내고 AI 응답이 도착하는지 확인하세요. 페이지가 열리는 것만으로 모델을 시험한 것은 아닙니다.
2. Telegram과 목표 작업. 봇을 설정하고 자신의 페어링을 승인한 뒤 Telegram에서 그 봇에 새 메시지를 보내고 답변이 그곳에 도착하는지 확인하세요. 이어서 읽기를 허용한 무해한 테스트 폴더 요약처럼 범위가 작고 결과를 확인할 수 있는 작업 하나를 시험하세요. 알림은 저장된 일정과 실제 도착 여부를 따로 확인하세요. 대시보드의 응답은 Telegram 전달이나 예약 실행을 입증하지 않습니다.
3. 예약 작업. 어시스턴트는 일정에 따라 작업을 실행할 수 있습니다. 예를 들면 Telegram으로 아침 요약을 보내거나 주기적으로 이메일을 확인하는 작업입니다. 그래서 게이트웨이를 하루 종일 실행해 두는 것입니다.
4. 기억. OpenClaw는 작업 폴더의 일반적인 Markdown 파일에 장기 기억을 저장합니다. 사용자가 누구인지, 어떻게 응답해야 하는지, 이전 대화에서 무엇을 기억했는지가 담깁니다. 파일을 직접 열어 읽을 수 있으므로 내부를 알 수 없는 블랙박스가 아닙니다.
5. 스킬. 프로젝트에는 보안 검사가 내장된 기성 스킬과 플러그인 카탈로그가 있습니다. 다른 사람이 만든 스킬은 내 기기에서 실행되는 다른 사람의 코드이므로 카탈로그가 이를 확인합니다.

여기에는 규칙이 하나 있습니다. 모든 기능을 한꺼번에 켜지 마세요. 안정적인 대화 하나부터 시작한 다음 Telegram을 연결하고, 그다음 일정을 설정하세요. 이렇게 하면 문제가 생겼을 때 “전부 고장 났는데 어디서부터 잘못됐는지 모르겠다”는 상황 대신 각 단계에서 문제를 발견할 수 있습니다.

설치에 문제가 생기면 어떻게 해야 하나요?#

흔한 상황 세 가지를 살펴보겠습니다.

설치 직후 “openclaw: command not found”가 표시됩니다. 거의 항상 경로 문제입니다. npm 전역 패키지 폴더가 터미널의 PATH에 포함되어 있지 않은 것입니다. 문서에 나온 진단 명령은 다음과 같습니다.

node -v
npm prefix -g
echo "$PATH"

두 번째 명령이 출력한 경로가 세 번째 출력에도 포함되어야 합니다. 그렇지 않다면 셸 설정에 경로를 추가하거나 터미널을 닫았다가 다시 여세요. 설치 후 새 세션에서야 Node 경로가 표시되는 경우도 있습니다.

게이트웨이가 실행 중인데 어시스턴트가 응답하지 않습니다. 문서 FAQ에 나오는 증상입니다. 첫 메시지에 답이 없고 토큰 카운터가 0입니다. 에이전트가 시작조차 되지 않았다는 뜻입니다. 대개 모델이 설정되지 않은 경우입니다. 다음 순서로 확인하세요.

openclaw gateway restart
openclaw status
openclaw models status

모델이 설정되어 있는데도 응답이 없다면 openclaw logs --follow를 실행해 실시간 로그와 작업이 멈춘 지점을 확인하세요.

Telegram 봇이 응답하지 않습니다. 다음 순서로 확인하세요. 토큰이 현재 메시지를 보내는 봇의 것인지, 게이트웨이가 실행 중인지(openclaw gateway status), 페어링이 승인되었는지(openclaw pairing list telegram) 확인합니다. 페어링 코드는 한 시간 동안 유효합니다. 어제 봇에 메시지를 보냈다면 다시 메시지를 보내고 새 코드를 승인하세요.

완전히 막혔다면 문서는 뜻밖이지만 합리적인 방법을 제안합니다. 내 기기를 볼 수 있는 로컬 AI 에이전트에 진단 정보를 제공하는 것입니다. openclaw status --all과 openclaw doctor의 출력을 받은 Claude Code나 Codex는 지원 채팅보다 구성을 더 빠르게 파악할 수 있습니다. AI가 AI를 고치는 셈입니다.

사람들이 OpenClaw에 대해 자주 묻는 다른 질문은 무엇인가요?#

Ailoot에 대해 알아보세요.