OpenClaw란? 설치부터 텔레그램·디스코드 활용까지 한 번에 정리

OpenClaw의 개념, 설치 전 확인 사항, npm 설치 예시, Telegram·Discord 연결 흐름, 터미널 점검 명령과 보안 체크리스트를 정리했습니다.

OpenClaw를 먼저 이해하면

OpenClaw는 내 컴퓨터나 개인 서버에 설치해 사용하는 self-hosted AI assistant에 가깝습니다. 공식 문서에서는 Discord, Telegram, Signal, Slack, WhatsApp 같은 채널을 AI coding agent와 연결하는 Gateway로 설명합니다.

OpenClaw 자체가 새로운 채팅 앱인 것은 아닙니다. 로컬에서 실행되는 Gateway가 있고, 이 Gateway가 AI 모델, 메신저 채널, 터미널 명령을 이어주는 구조입니다.

사용자는 텔레그램이나 디스코드에서 메시지를 보내고, OpenClaw는 설정된 모델과 도구를 통해 답변하거나 작업을 처리합니다. 그래서 설치 과정도 ‘앱 설치 후 로그인’보다는 CLI 설치 → Gateway 실행 → 채널 연결 → pairing 승인 순서로 보는 편이 맞습니다.

이 글은 OpenClaw가 무엇인지, 설치 전에 무엇을 확인해야 하는지, 텔레그램·디스코드·터미널에서는 어떤 흐름으로 쓰는지를 정리한 글입니다. 다만 OpenClaw는 문서와 명령어가 바뀔 수 있는 도구라서, 실제 설치 직전에는 docs.openclaw.ai와 github.com/openclaw/openclaw의 최신 내용을 다시 확인하는 것이 좋습니다.

왜 텔레그램·디스코드에서 쓰는가

OpenClaw를 메신저에 연결하는 이유는 평소 쓰는 채팅방에서 AI 에이전트에게 바로 지시할 수 있기 때문입니다. 터미널을 계속 열어두지 않아도 텔레그램 DM으로 작업 정리를 요청하거나, 디스코드 개인 서버에서 채널별로 맥락을 나눌 수 있습니다.

다만 접근이 쉬워지는 만큼 권한 관리가 중요해집니다. OpenClaw는 단순 답변용 챗봇보다 더 넓은 작업 권한을 가질 수 있으므로, 누가 봇에게 말을 걸 수 있는지 제한하는 설정을 먼저 봐야 합니다.

구분	추천 상황	주의할 점
터미널	설치 확인, 오류 점검, 직접 테스트	로그와 상태 명령을 확인할 수 있어야 함
텔레그램	개인 DM으로 빠르게 쓰고 싶을 때	BotFather 토큰과 user ID 관리 필요
디스코드	개인 서버에서 채널별 작업을 나눌 때	Developer Portal 권한 설정 필요

처음 쓰는 분이라면 터미널에서 설치와 doctor 확인을 끝낸 뒤, 텔레그램 DM부터 연결하는 순서가 무난합니다. 디스코드는 서버 권한, intent, 초대 URL까지 확인해야 해서 첫 설정 단계가 조금 더 많습니다.

설치 전에 확인할 것

OpenClaw 설치 문서는 macOS, Linux, Windows 환경을 함께 다룹니다. Windows에서는 네이티브 설치도 가능하지만, 개발이나 자동화 작업까지 염두에 둔다면 WSL2 환경도 함께 검토할 만합니다.

Node.js 버전 기준은 문서 업데이트에 따라 달라질 수 있습니다. 현재 안내 흐름에서는 최소 Node 22 이상을 요구하는 내용이 보이고, 일부 안내에서는 Node 24 사용을 권장합니다. 설치 오류를 줄이려면 최신 LTS 또는 공식 문서에서 권장하는 버전으로 맞추는 것이 좋습니다.

설치 전에 준비할 항목은 아래 정도입니다.

• Node.js 실행 환경
• OpenClaw CLI
• 사용할 LLM API 키 또는 로컬 모델 환경
• Telegram bot token 또는 Discord bot token
• 터미널에서 PATH를 확인할 수 있는 기본 지식

여기서 가장 중요한 것은 토큰 관리입니다. Telegram BotFather 토큰, Discord bot token, LLM API key는 비밀번호처럼 다뤄야 합니다. 캡처 이미지, 블로그 글, 공개 채팅방에 그대로 올리면 안 됩니다.

반응형

설치와 기본 상태 확인

npm으로 설치하는 흐름은 아래처럼 볼 수 있습니다. 공식 문서에서는 npm i -g openclaw 형태도 안내하므로, 실제 명령은 최신 문서를 기준으로 맞추는 편이 안전합니다.

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

openclaw onboard --install-daemon은 초기 설정을 진행하면서 Gateway를 백그라운드 서비스로 등록하는 흐름입니다. macOS에서는 LaunchAgent, Linux에서는 systemd user service 같은 방식으로 관리될 수 있습니다.

설치 후에는 바로 메신저 연결로 넘어가지 말고 상태부터 확인합니다.

openclaw --version
openclaw doctor
openclaw gateway status
openclaw status

openclaw doctor는 설정 문제, 보안상 위험한 구성, 오래된 설정 등을 점검할 때 사용합니다. openclaw gateway status는 Gateway 서비스 상태와 연결 가능 여부를 확인하는 명령으로 보면 됩니다.

정상 설치 여부를 확인하지 않은 상태에서 텔레그램이나 디스코드부터 연결하면 문제가 봇 토큰인지, Gateway인지, 권한 설정인지 구분하기 어렵습니다. 설치 확인 → doctor → Gateway status 순서로 보는 것이 좋습니다.

텔레그램에서 활용하는 흐름

텔레그램 연결은 BotFather에서 봇을 만들고, 받은 bot token을 OpenClaw 설정에 연결하는 방식입니다. 텔레그램에서 @BotFather를 열고 /newbot을 실행한 뒤 안내에 따라 이름과 username을 정하면 토큰을 받을 수 있습니다.

OpenClaw 문서에서는 Telegram 기본 DM 정책을 pairing 중심으로 설명합니다. 모르는 사용자가 봇에게 말을 걸면 바로 처리하지 않고, 짧은 pairing code를 만든 뒤 소유자가 승인하는 흐름입니다.

기본 흐름은 아래 순서로 잡으면 됩니다.

1. BotFather에서 봇 생성
2. bot token 저장
3. OpenClaw Telegram 채널 활성화
4. Gateway 실행
5. 봇에게 DM 보내기
6. pairing 요청 확인
7. 터미널에서 승인

승인 명령 예시는 아래와 같습니다.

openclaw pairing list telegram
openclaw pairing approve telegram <CODE>

문서상 pairing code는 8자리 대문자 코드이며, 일정 시간이 지나면 만료됩니다. 승인된 사용자 정보는 로컬 credential 쪽에 저장되므로, 관련 파일도 민감한 정보로 취급해야 합니다.

그룹에서 쓸 때는 더 신중해야 합니다. 그룹 ID와 사용자 ID는 역할이 다릅니다. 그룹 ID는 어떤 방에서 봇이 동작할지 정할 때 쓰이고, 사용자 ID는 누가 봇을 사용할 수 있는지 제한할 때 씁니다.

처음에는 개인 DM에서만 테스트하고, 그룹에서는 requireMention 같은 호출 제한을 켜는 편이 안전합니다. 공개 그룹에 바로 연결하는 방식은 권하지 않습니다.

디스코드에서 활용하는 흐름

디스코드는 텔레그램보다 준비 단계가 조금 더 많습니다. Discord Developer Portal에서 Application을 만들고 Bot을 추가한 뒤, bot token을 OpenClaw가 실행되는 PC나 서버에 설정해야 합니다.

공식 문서 흐름상 Discord는 bot token을 설정하고, 메시지를 읽기 위한 권한과 intent를 확인해야 합니다. 특히 Message Content Intent는 메시지 내용을 다루는 봇 설정에서 빠뜨리기 쉬운 항목입니다.

설정 흐름은 아래처럼 잡으면 됩니다.

1. Discord Developer Portal에서 Application 생성
2. Bot 생성 후 token 발급
3. Message Content Intent 확인
4. 필요한 경우 Server Members Intent 확인
5. OAuth2 URL Generator에서 bot 권한 선택
6. 내 개인 서버에 봇 초대
7. Server ID, User ID 확인
8. OpenClaw 설정에 Discord token 연결
9. DM 또는 서버에서 pairing 승인

토큰은 환경변수로 관리할 수 있습니다. 예시는 아래처럼 쓰되, 실제 토큰을 화면에 노출하지 마세요.

export DISCORD_BOT_TOKEN="YOUR_BOT_TOKEN"

pairing 승인 명령은 텔레그램과 비슷합니다.

openclaw pairing list discord
openclaw pairing approve discord <CODE>

디스코드의 장점은 개인 서버 안에 #coding, #research, #memo 같은 채널을 만들고 작업 맥락을 나눌 수 있다는 점입니다. 다만 처음부터 여러 사람이 있는 서버에 연결하기보다는, 혼자 쓰는 테스트 서버에서 권한과 mention 동작을 먼저 확인하는 편이 안전합니다.

터미널에서 바로 써보는 방법

터미널은 OpenClaw를 설치하고 점검하는 기본 조작 지점입니다. 메신저에서 답이 오지 않을 때도 로그와 Gateway 상태는 결국 터미널에서 확인해야 하므로, 몇 가지 명령은 익숙해지는 것이 좋습니다.

가장 먼저 볼 명령은 아래입니다.

openclaw --version
openclaw doctor
openclaw gateway status
openclaw logs --follow

openclaw logs --follow는 Gateway 로그를 따라가며 볼 때 유용합니다. 봇이 메시지를 받는지, pairing 요청이 들어오는지, 토큰 오류가 나는지 확인할 수 있습니다.

Gateway를 백그라운드 서비스가 아니라 직접 보면서 실행하고 싶다면 아래처럼 foreground로 띄울 수 있습니다.

openclaw gateway stop
openclaw gateway --port 18789 --verbose

CLI에서 에이전트에게 직접 메시지를 보내는 흐름도 있습니다. 공식 CLI 문서에서는 openclaw agent가 Gateway를 통해 agent turn을 실행하는 명령으로 안내됩니다.

openclaw agent --agent default --message "오늘 작업 체크리스트 정리해줘" --thinking high

환경에 따라 --agent, --to, --session-key 같은 선택자가 필요할 수 있습니다. 처음에는 문서 예시를 그대로 복사하기보다, 내 설정에 등록된 agent ID와 channel binding을 확인한 뒤 테스트하세요.

흔한 문제와 먼저 볼 항목

OpenClaw에서 막히는 지점은 대체로 설치 자체보다 경로, 토큰, 권한, pairing 상태 쪽입니다. 아래 표부터 확인하면 원인을 좁히기 쉽습니다.

증상	먼저 볼 것
openclaw 명령을 못 찾음	Node 전역 bin 경로와 PATH
Gateway가 안 뜸	openclaw doctor, openclaw gateway status
봇이 답하지 않음	openclaw logs --follow, pairing 승인 여부
Telegram 401 오류	BotFather token 오타 또는 만료 여부
Discord 메시지가 안 보임	Message Content Intent, bot 권한, mention 필요 여부
설정 변경 후 그대로임	Gateway restart 또는 service 재시작 여부

Telegram 401은 토큰 문제일 가능성이 큽니다. Discord는 token이 맞아도 메시지를 못 읽는 경우가 있어서, Developer Portal의 intent와 서버 초대 권한을 함께 확인해야 합니다.

문제가 반복되면 openclaw status --deep이나 openclaw gateway status --deep처럼 더 자세한 점검 명령을 사용할 수 있습니다. 다만 deep 점검은 시간이 더 걸릴 수 있으니, 기본 상태 확인이 끝난 뒤에 쓰는 편이 좋습니다.

주의할 점과 마무리 체크리스트

OpenClaw는 편리하지만 일반 채팅봇처럼 열어두면 위험할 수 있습니다. bot token, API key, pairing code는 공개하면 안 되고, DM을 누구에게나 열어두는 설정도 신중하게 다뤄야 합니다.

처음 쓰는 분에게 권하는 순서는 명확합니다. 터미널 설치와 doctor 확인 → Telegram 개인 DM 연결 → 필요할 때 Discord 개인 서버로 확장하는 흐름이 가장 단순합니다.

공개 그룹이나 여러 사람이 있는 서버에 바로 연결하는 것은 권하지 않습니다. 먼저 allowlist, pairing, requireMention 동작을 확인하고, 어떤 사용자가 어떤 권한으로 봇을 호출할 수 있는지 정리한 뒤 확장하세요.

마지막 체크리스트입니다.

• 공식 문서와 GitHub README에서 최신 설치 명령 확인
• Node.js 요구 버전 확인
• npm install -g openclaw@latest 또는 공식 문서의 npm 명령 실행
• openclaw onboard --install-daemon으로 초기 설정 진행
• openclaw doctor와 openclaw gateway status로 상태 확인
• Telegram은 BotFather token과 pairing 승인부터 테스트
• Discord는 Developer Portal, intent, 초대 권한, Server/User ID 확인
• token, API key, pairing code를 캡처나 글에 노출하지 않기
• 개인용은 pairing 또는 allowlist 중심으로 시작하기

정리하면 OpenClaw는 메신저에서 호출할 수 있는 로컬 AI 에이전트 환경으로 이해하면 됩니다. 설치 명령보다 더 중요한 것은 Gateway가 정상인지, 누가 접근할 수 있는지, 문제가 생겼을 때 터미널에서 확인할 수 있는지입니다. 이 세 가지를 먼저 잡으면 텔레그램·디스코드·터미널 활용 흐름이 훨씬 단순해집니다.