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

OpenClaw 개념부터 설치 준비물, npm 설치, Gateway 점검, Telegram·Discord 연동, 터미널 활용, 오류 해결과 보안 체크까지 덜 헤매도록 정리했어요.

OpenClaw, 이름은 생소한데 하는 일은 꽤 직관적이에요

OpenClaw를 처음 검색하면 살짝 헷갈려요. 메신저 봇 같기도 하고, AI 에이전트 실행 도구 같기도 하고, 뭔가 이름부터 범위가 넓어 보이거든요. 근데 핵심만 잡으면 생각보다 단순해요.

OpenClaw는 내 컴퓨터나 서버에 직접 띄워두는 self-hosted AI Gateway에 가까워요. 공식 문서에서는 Discord, Telegram, WhatsApp, Slack 같은 채팅 채널을 하나의 Gateway로 묶고, 그 뒤에 AI 에이전트를 연결하는 구조로 설명해요. 설치 전에는 https://docs.openclaw.ai/ 문서를 한 번 확인해두는 게 좋아요.

일반 챗봇은 보통 웹이나 앱 안에서 대화하고 끝나잖아요. OpenClaw는 Gateway가 백그라운드에서 떠 있고, 터미널·텔레그램·디스코드로 들어온 메시지를 에이전트 세션으로 넘기는 쪽에 가까워요. 여러 채널에서 부를 수 있는 AI 작업 리모컨이라고 보면 감이 좀 빨리 와요.

다만 기대치를 처음부터 너무 올리면 안 돼요. 파일, API 키, 메신저 토큰, 외부 스킬이 엮일 수 있는 도구라서 편한 만큼 조심할 것도 많거든요. 회사 계정이나 중요한 개인 계정에 바로 붙이는 건 조금 빠른 선택이에요.

설치 전 준비물: Node, API 키, 그리고 테스트용 환경

설치 전에 제일 먼저 볼 건 Node.js예요. 공식 설치 문서 기준으로는 Node 24를 권장하고, Node 22.19 이상도 조건으로 안내돼요. 이런 조건은 바뀔 수 있으니 시작 직전에 https://docs.openclaw.ai/install 페이지를 다시 보는 게 마음 편해요.

터미널에서는 일단 이렇게 확인해요.

node --version
npm --version

여기서 Node 버전이 낮으면 nvm으로 올리는 쪽이 편해요. 윈도우라면 PowerShell에서 바로 씨름하기보다 WSL2에서 먼저 테스트하는 편이 덜 꼬일 때가 많고요. 진짜 설치형 도구는 초반 환경에서 반은 갈리더라고요.

LLM API 키도 필요해요. OpenClaw가 답변하고 판단하려면 OpenAI, Anthropic, xAI 같은 모델 제공자 키나 로컬 모델 설정이 있어야 하거든요. OpenClaw만 설치했다고 모델 비용까지 같이 해결되는 구조는 아니니까, 가격이나 정책은 각 서비스의 최신 안내를 따로 봐야 해요.

테스트 환경은 따로 두는 걸 추천해요. WSL, VM, 남는 미니 PC, VPS처럼 메인 작업 공간과 조금 떨어진 곳이면 좋아요. 공식 문서에서도 토큰, allowlist, Gateway 접근 제어 같은 보안 항목을 따로 다루고 있어서 처음부터 내 모든 자료에 접근 가능한 상태로 열어두는 건 피하는 게 맞아요.

설치 순서: npm 설치 후 onboard부터 확인해요

설치 방법은 공식 문서에 installer 방식과 npm 방식이 같이 나와요. 처음 만지는 도구라면 npm 방식이 조금 더 마음 편할 수 있어요. 어떤 명령을 치고 있는지 흐름이 보이거든요.

기본 설치 예시는 이렇게 잡으면 돼요.

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

openclaw onboard --install-daemon은 초기 설정을 진행하면서 Gateway를 백그라운드 서비스로 등록하는 흐름이에요. 공식 설치 문서에서도 이 단계에서 LLM 연결, Gateway daemon 설치, 메시징 채널 연결을 함께 처리한다고 안내해요.

공식 installer를 쓰고 싶다면 문서에 나온 one-liner도 있어요.

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

근데 curl | bash는 치기 전에 한 번 더 보는 게 좋아요. 공식 도메인이 맞는지, 문서에 있는 명령이 맞는지, 지금 테스트 머신에서 실행하는 게 맞는지요. 별거 아닌데 이 확인 한 번이 나중에 덜 찝찝해요.

설치 후에는 바로 텔레그램부터 붙이지 말고 상태 확인을 먼저 해요.

openclaw --version
openclaw doctor
openclaw status

공식 문서에는 openclaw status, openclaw chat 같은 검증 명령도 안내돼요. 내가 쓰는 버전에서 doctor나 세부 명령이 다르게 동작하면 openclaw --help와 최신 문서를 먼저 맞춰보는 게 좋아요. OpenClaw처럼 빠르게 바뀌는 도구는 여기서 은근 차이가 나요.

터미널에서 쓰는 흐름: Gateway 켜고 상태부터 보기

터미널 활용에서 제일 중요한 건 Gateway예요. 이게 떠 있어야 텔레그램이든 디스코드든 들어온 메시지가 처리돼요. 봇 토큰을 아무리 잘 넣어도 Gateway가 꺼져 있으면 그냥 아무 반응이 없어요. 이게 또 은근 당황스러워요.

디버깅할 때는 백그라운드 서비스보다 로그가 보이는 실행이 편해요.

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

공식 문서에서도 Gateway 기본 포트로 18789를 안내해요. 포트를 바꿔 실행한다면 방화벽, reverse proxy, 다른 프로세스와의 충돌도 같이 봐야 해요.

터미널에서 바로 말을 걸어보는 단계도 넣어두면 좋아요. 공식 설치 문서에는 openclaw chat 예시가 있고, 문서나 버전에 따라 agent 계열 명령 예시가 보일 수도 있어요.

openclaw chat '오늘 작업 로그를 요약해줘'
# 사용 중인 버전에서 지원한다면
openclaw agent --message '오늘 작업 로그를 요약해줘' --thinking high

저라면 이 단계를 꼭 거쳐요. 터미널에서 답이 오면 모델 API와 OpenClaw 기본 런타임은 일단 살아 있는 거고, 그다음부터 Telegram·Discord 채널 문제만 보면 되거든요. 반대로 여기서 안 되면 메신저를 붙여도 삽질이 길어져요.

상황	Openclaw 한테 시킬만한 일
작업 시작 전	오늘 할 일, 저장소 상태, 미확인 이슈 정리
배포 전	체크리스트 생성, 로그 요약, 위험 변경점 질문
외출 중	텔레그램 DM으로 서버 상태 확인 요청
팀 채널	디스코드에서 작업 요약이나 링크 정리 요청

 

다만 파일 수정, 배포, 외부 메시지 발송처럼 되돌리기 귀찮은 일은 승인 흐름을 두는 게 좋아요. 편하다고 전부 자동으로 열어두면 나중에 내가 만든 자동화인데 내가 제일 못 믿는 상황이 와요.

텔레그램 연동: BotFather 토큰 넣고 pairing 승인하기

텔레그램은 OpenClaw 입문용 채널로 꽤 무난해요. 공식 Telegram 문서에서도 BotFather로 토큰을 만들고, config나 환경변수에 넣은 뒤 Gateway를 시작하는 흐름을 안내해요. 문서는 https://docs.openclaw.ai/channels/telegram 에서 확인할 수 있어요.

순서는 이렇게 보면 돼요.

1. Telegram에서 @BotFather 검색
2. /newbot 입력
3. 봇 이름과 username 생성
4. BotFather가 준 token 복사
5. OpenClaw config 또는 환경변수에 token 설정
6. gateway 실행
7. 첫 DM pairing 코드 승인

설정 파일은 보통 ~/.openclaw/openclaw.json 쪽을 먼저 봐요. 실제 구조는 버전에 따라 JSON5처럼 보일 수 있으니, 공식 문서와 내 파일 구조를 같이 맞춰야 해요.

{ "channels": { "telegram": { "enabled": true, "botToken": "123:abc...", "dmPolicy": "pairing" } } }

여기서 실제 토큰은 절대 캡처하지 마세요. 블로그 글 쓰다가 터미널이나 설정 파일 캡처에 토큰이 그대로 찍히는 경우가 있는데, 그때는 바로 재발급해야 해요. 대충 일부 가렸으니까 괜찮겠지, 이것도 별로예요.

환경변수로 넣는 방식도 있어요.

export TELEGRAM_BOT_TOKEN='123:abc...'
openclaw gateway

다만 현재 터미널에만 export하면 재부팅이나 서비스 재시작 뒤에 사라질 수 있어요. 백그라운드 서비스로 오래 돌릴 거면 서비스가 읽을 수 있는 env 파일이나 설정 방식을 따로 맞춰야 해요.

첫 DM은 pairing이 걸릴 수 있어요. 공식 Telegram 문서도 기본 DM 정책으로 pairing을 설명하고, pairing code에는 제한 시간이 있다고 안내해요.

openclaw pairing list telegram
openclaw pairing approve telegram <CODE>

처음에는 개인 DM에서만 테스트하세요. 그룹방은 privacy mode, group chat ID, allowlist, mention 조건이 한 번에 엮여요. 이걸 처음부터 같이 하면 진짜 어디서 막힌 건지 감이 안 와요.

디스코드 연동: DM부터 확인하고 서버 권한은 나중에 보기

디스코드는 텔레그램보다 손이 조금 더 가요. 봇 만들고 토큰 넣었는데 서버에서 말이 없으면 순간 ‘아니 뭐가 또 빠진 거야’ 싶어지거든요. 보통은 Intent, 초대 권한, 채널 권한, mention 조건 중 하나예요.

공식 Discord 문서에서는 Developer Portal에서 Application을 만들고 Bot을 추가한 뒤, Message Content Intent를 켜는 흐름을 안내해요. Server Members Intent는 역할 allowlist나 ID 매칭에 필요할 수 있고, Presence Intent는 상황에 따라 선택이에요. 문서는 https://docs.openclaw.ai/channels/discord예요.

대략 흐름은 이렇게 잡으면 돼요.

Discord Developer Portal
→ New Application
→ Bot 생성
→ Message Content Intent 활성화
→ Bot token 복사
→ OAuth2에서 bot, applications.commands scope로 서버 초대
→ OpenClaw config 또는 환경변수에 token 설정
→ gateway 실행
→ DM pairing 승인

토큰은 환경변수로 두는 편이 낫고, 공식 문서도 SecretRef 형태의 설정 예시를 보여줘요.

export DISCORD_BOT_TOKEN='YOUR_BOT_TOKEN'
openclaw gateway

서버에 넣기 전에 DM으로 먼저 확인하는 걸 추천해요. DM에서 되는데 서버에서만 안 되면 OpenClaw 설치 문제보다는 guild allowlist, 채널 권한, requireMention, 봇 초대 scope 쪽을 보면 돼요. 이렇게 나눠서 보면 원인을 훨씬 빨리 좁힐 수 있어요.

Discord도 pairing 흐름이 있어요.

openclaw pairing list discord
openclaw pairing approve discord <CODE>

서버 채널에서는 기본적으로 mention이 필요할 수 있어요. 공식 문서도 guild 메시지는 mention-gated가 기본이라고 설명해요. 그러니까 서버에서 그냥 ‘안녕’만 치고 봇이 조용하다고 바로 실패 판정하지 말고, 먼저 봇 멘션으로 테스트해보는 게 좋아요.

자주 막히는 오류: 답장 안 함, command not found, 토큰 꼬임

처음 설치하고 제일 허무한 순간은 이거예요. 분명히 다 한 것 같은데 봇이 아무 말도 안 해요. 조용함. 너무 조용함. 이럴 땐 설정을 갈아엎기 전에 한 단계씩 끊어서 봐야 해요.

먼저 기본 명령부터 확인해요.

openclaw --version
openclaw doctor
openclaw status

openclaw 자체가 안 잡히면 PATH 문제일 가능성이 커요. npm 글로벌 설치 경로가 현재 shell PATH에 들어갔는지 확인하고, zsh·bash·WSL을 섞어 쓰고 있다면 어느 터미널에서 설치했는지도 같이 봐야 해요.

Gateway 로그도 꼭 봐요.

openclaw gateway status
openclaw gateway --port 18789 --verbose

verbose 로그에서 모델 API 인증 오류가 보이면 Telegram token을 다시 만들어도 해결이 안 돼요. 이게 은근 흔한 함정이에요. 메신저는 메시지를 잘 넘겼는데, 뒤에서 모델 호출이 실패하는 경우가 있거든요.

Telegram 증상	확인할 것
봇이 메시지를 못 받음	BotFather token, config 위치, Gateway 실행 여부
pairing 코드만 나오고 처리 안 됨	openclaw pairing list telegram 후 approve 여부
예전 봇으로 계속 연결됨	config에 남은 stale token, Gateway 재시작 여부
그룹에서만 무응답	privacy mode, group ID, mention 조건, allowlist

Discord 증상	확인할 것
DM에서 안 됨	bot token, Gateway, Message Content Intent, pairing 승인
DM은 되는데 서버에서 안 됨	OAuth2 scope, 서버/채널 권한, guild allowlist
봇이 입력 중 표시만 함	모델 API 오류, visible reply 설정, 로그 확인
특정 채널에서만 안 됨	채널별 권한, requireMention, thread 권한

설정 파일을 AI에게 바로 고치게 하는 건 조심하는 편이 좋아요. openclaw.json이 깨지면 재온보딩을 해도 애매하게 꼬일 수 있어요. 수정 전에는 파일을 복사해두고, 바꾼 뒤에는 openclaw doctor로 확인하는 흐름이 마음 편해요.

보안 체크: 편한 만큼 권한을 작게 줘야 해요

OpenClaw의 매력은 메신저에서 AI를 바로 부를 수 있다는 점이에요. 근데 반대로 말하면, 메신저 메시지가 작업 지시가 될 수도 있다는 뜻이에요. 이 부분은 가볍게 넘기면 안 돼요.

공식 Telegram·Discord 문서 모두 DM policy, pairing, allowlist, group policy 같은 접근 제어를 다뤄요. dmPolicy: "open"에 wildcard를 넣는 식의 설정은 일부러 공개 봇을 운영하는 경우가 아니라면 피하는 게 좋아요.

Gateway도 외부에 바로 열지 않는 편이 안전해요. 기본 로컬 주소와 포트는 127.0.0.1:18789 쪽으로 안내되지만, 원격에서 쓰고 싶다고 무작정 public IP에 붙이면 위험해질 수 있어요. 원격 접근이 필요하면 공식 문서의 remote access 안내나 Tailscale 같은 접근 제어 방식을 먼저 검토하는 게 좋아요.

스킬 설치도 마찬가지예요. 기능을 늘려주는 건 좋지만, 결국 내 에이전트가 읽고 실행할 수 있는 지시와 도구를 추가하는 일이거든요. 출처가 애매한 스킬을 막 넣는 건 추천하기 어려워요.

최소 기준은 이렇게 잡으면 돼요.

• Telegram·Discord 토큰은 절대 공개하지 않기
• 봇은 전용 계정이나 테스트 서버에서 먼저 만들기
• DM은 pairing 또는 allowlist로 시작하기
• 그룹·서버는 허용 ID와 mention 조건을 먼저 걸기
• Gateway를 공용 인터넷에 바로 노출하지 않기
• config 수정 전 백업하기
• 스킬은 필요한 것만 설치하고 출처 확인하기
• 설정 변경 후 openclaw doctor 다시 돌리기

완벽하게 안전하다는 말은 여기서 좀 과해요. 대신 사고 날 면적을 줄이는 게 현실적인 목표예요. 자동화 도구는 똑똑한 것보다 통제 가능한 게 먼저예요.

터미널 → 텔레그램 DM → 디스코드 서버 순서가 덜 꼬여요

정리하면 OpenClaw는 여러 메신저에서 부를 수 있는 self-hosted AI Gateway로 이해하면 제일 편해요. 터미널은 설치와 점검용, 텔레그램은 개인 리모컨, 디스코드는 팀 채널 인터페이스에 가까워요.

처음부터 Telegram, Discord, 서버, 스킬, 자동화까지 한 번에 붙이면 어디서 터졌는지 찾기 힘들어요. 그래서 순서는 이렇게 가는 게 덜 피곤해요.

1. Node 버전 확인
2. OpenClaw 설치
3. onboard 실행
4. openclaw doctor / status 확인
5. 터미널에서 chat 또는 agent 메시지 테스트
6. Telegram DM 연결
7. Telegram pairing 승인
8. Discord DM 테스트
9. Discord 서버 초대와 권한 조정
10. 필요한 skill만 추가

체크	확인할 내용
설치	npm install -g openclaw@latest 또는 공식 installer 사용
초기화	openclaw onboard --install-daemon 실행
점검	openclaw --version, openclaw doctor, openclaw status 확인
터미널	openclaw chat 또는 현재 버전의 agent 명령으로 응답 확인
텔레그램	BotFather token, config/env, pairing approve 확인
디스코드	Developer Portal, Bot token, Message Content Intent, DM pairing 확인
서버	guild allowlist, 채널 권한, requireMention 확인
보안	토큰 비공개, allowlist, 전용 환경, 스킬 출처 확인

이 정도만 잡고 시작해도 ‘왜 안 되지?’ 하는 구간이 꽤 줄어요. OpenClaw는 잘 붙이면 확실히 재미있는 도구예요. 다만 권한이 큰 자동화 도구라는 점은 계속 기억하고 쓰는 게 좋아요.