OpenClaw 설치 절차: Node.js 환경과 Telegram 연결 확인

오픈클로(OpenClaw)를 처음 설치할 때 가장 헷갈리는 지점은 “설치가 안 된 건지, Telegram 연결만 안 된 건지”가 섞이는 순간입니다. 그래서 이 글은 바로 Telegram부터 붙이지 않고, 먼저 내 컴퓨터에서 OpenClaw가 정상 작동하는지 확인한 다음 Telegram 봇을 연결하는 순서로 진행합니다.

최종 목표는 간단합니다. 설치환경을 확인하고, OpenClaw를 설치한 뒤, Telegram에서 내 OpenClaw 에이전트에게 첫 메시지를 보내는 것입니다.

전체 흐름 요약 ― 먼저 로컬 확인, 그다음 Telegram 연결

처음부터 Telegram 연결만 바라보면, 오류가 났을 때 원인을 찾기 어렵습니다. 아래 순서대로 진행하면 문제 구간을 훨씬 쉽게 나눌 수 있습니다.

설치 전 준비물

설치 전에 필요한 것을 먼저 정리해 두면 중간에 멈추는 일이 줄어듭니다.

1단계 ― Node.js와 터미널 환경 확인

OpenClaw를 실행하려면 JavaScript 실행 환경인 Node.js가 필요합니다. 먼저 터미널을 열고 아래 명령어를 입력합니다.

node -v

정상이라면 `v24.x.x` 또는 지원 범위의 Node 22 LTS 버전이 출력됩니다. 아무것도 나오지 않거나 너무 오래된 버전이 나온다면 Node.js부터 설치해야 합니다.

macOS에서는 Homebrew로 `brew install node`를 사용할 수 있고, Linux에서는 배포판 패키지 매니저나 NodeSource 설치 흐름을 사용할 수 있습니다. 설치 후에는 새 터미널을 열고 다시 `node -v`를 확인하세요.

2단계 ― OpenClaw 설치

공식 문서 기준 가장 빠른 설치 방법은 설치 스크립트를 실행하는 것입니다. 운영체제에 맞는 명령어를 사용하세요.

macOS / Linux / WSL2

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

이 명령어는 OpenClaw 설치 스크립트를 내려받아 실행합니다. 처음 실행하는 명령어이므로, 가능하면 공식 문서의 최신 설치 페이지와 함께 확인한 뒤 진행하는 것이 좋습니다.

Windows PowerShell

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

Windows에서도 설치는 가능하지만, 터미널·권한·환경변수 문제를 줄이고 싶다면 WSL2에서 macOS/Linux 흐름으로 설치하는 편이 더 안정적입니다.

Node를 직접 관리하는 경우

npm install -g openclaw@latest

설치가 끝났다면 아래 명령어로 OpenClaw CLI가 정상적으로 잡혔는지 확인합니다.

openclaw --version
openclaw doctor

`openclaw –version`에서 버전이 나오고, `openclaw doctor`에서 큰 오류가 없다면 다음 단계로 넘어가면 됩니다.

3단계 ― 온보딩 실행

설치가 끝났다면 초기 설정을 돕는 온보딩을 실행합니다.

openclaw onboard --install-daemon

온보딩은 모델 인증, workspace, Gateway 포트와 인증 방식, 채널, daemon, health check, skills 같은 기본 설정을 안내합니다. `–install-daemon` 옵션은 macOS의 LaunchAgent, Linux/WSL2의 systemd user service처럼 OpenClaw가 백그라운드에서 계속 실행될 수 있게 돕는 흐름입니다.

4단계 ― Gateway와 Dashboard에서 먼저 작동 확인

Telegram을 연결하기 전에 OpenClaw 자체가 잘 설치됐는지 확인해야 합니다. 이 단계를 건너뛰면 Telegram 문제가 생겼을 때 원인을 찾기 어렵습니다.

Gateway 상태 확인

openclaw gateway status

Gateway가 실행 중이고 포트가 정상적으로 잡혀 있다면 기본 동작은 통과한 것입니다.

Dashboard 열기

openclaw dashboard

브라우저에 Control UI가 열리고 간단한 채팅이 가능하다면, OpenClaw 설치 자체는 정상으로 볼 수 있습니다. 이제 Telegram 채널만 붙이면 됩니다.

5단계 ― BotFather에서 Telegram 봇 만들기

이제 OpenClaw와 대화할 창구인 Telegram 봇을 만듭니다.

6단계 ― OpenClaw에 Telegram token 연결

OpenClaw의 Telegram 채널은 `openclaw channels login telegram`으로 로그인하는 방식이 아니라, config나 환경변수에 bot token을 넣고 Gateway를 실행하는 흐름입니다.

공식 문서의 기본 예시는 아래와 같은 구조입니다. 실제 token은 예시처럼 본문이나 공개 저장소에 남기지 말고, 본인 환경에만 보관하세요.

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

기본 계정에서는 환경변수 fallback으로 `TELEGRAM_BOT_TOKEN=…` 형태를 사용할 수도 있습니다. 다만 처음에는 온보딩이나 설정 파일 흐름에서 “어디에 token이 들어갔는지”를 분명히 아는 것이 중요합니다.

7단계 ― Telegram DM에서 pairing 승인하기

설정을 저장하고 Gateway를 실행한 뒤, 새로 만든 Telegram 봇에게 DM으로 첫 메시지를 보냅니다. 그러면 봇이 바로 답하는 대신 pairing code를 안내할 수 있습니다.

터미널에서는 아래 순서로 pairing 요청을 확인하고 승인합니다.

openclaw gateway
openclaw pairing list telegram
openclaw pairing approve telegram <CODE>

<CODE> 자리에는 Telegram DM에서 받은 pairing code를 넣으면 됩니다. pairing code는 1시간 뒤 만료되므로, 시간이 지났다면 봇에게 다시 메시지를 보내 새 코드를 받아야 합니다.

이 과정은 내 Telegram 계정과 OpenClaw를 연결하는 안전장치입니다. DM pairing을 완료했다고 해서 모든 그룹 채팅 권한까지 자동으로 열리는 것은 아니므로, 그룹은 별도로 설정해야 합니다.

8단계 ― 첫 메시지 테스트

pairing 승인이 끝났다면 Telegram으로 돌아가 봇에게 짧은 메시지를 보내 보세요.

안녕, 지금 OpenClaw 연결됐어?

정상이라면 OpenClaw 에이전트가 Telegram DM으로 답변합니다. 여기까지 성공하면 기본 설치와 Telegram DM 연동은 끝난 것입니다.

그룹 채팅은 나중에 붙이는 편이 안전한 이유

Telegram 봇을 그룹에 초대하는 것은 1:1 DM보다 설정이 복잡합니다. Telegram 봇은 기본 Privacy Mode 때문에 그룹 내 모든 메시지를 보지 못할 수 있고, 그룹에서는 `groups`, `groupPolicy`, `requireMention`, sender allowlist 같은 설정이 함께 작동합니다.

처음 설치할 때는 DM부터 성공시키는 것이 좋습니다. DM이 정상 작동하면 OpenClaw와 Telegram token, pairing 흐름은 통과한 것이고, 그 다음 그룹 정책만 별도로 조정하면 됩니다.

보안 체크리스트

OpenClaw 공식 보안 문서는 OpenClaw를 “개인이 신뢰하고 관리하는 assistant” 모델로 설명합니다. 서로 신뢰하지 않는 여러 사람이 하나의 tool-enabled agent를 공유하는 구조는 권장하지 않습니다.

회사 문서나 고객정보를 에이전트에 입력할 계획이라면, 먼저 회사 문서 AI 입력 기준과 로컬 AI 도구 체크리스트도 함께 확인해 두는 것이 좋습니다.

자주 막히는 지점과 해결 힌트

자주 묻는 질문 (FAQ)

Q1. Node.js는 꼭 24 버전을 써야 하나요?

처음 설치한다면 Node 24를 권장합니다. 기존에 Node 22 LTS 최신 버전이 설치되어 있다면 지원 범위로 볼 수 있지만, 새 환경을 만든다면 권장 버전에 맞추는 편이 좋습니다.

Q2. Telegram bot token이 유출되면 어떻게 하나요?

token은 비밀번호처럼 다뤄야 합니다. 유출이 의심되면 BotFather에서 token을 재발급하고, 기존 token이 들어간 설정이나 환경변수도 즉시 교체하세요.

Q3. pairing을 완료하지 않으면 봇을 쓸 수 없나요?

`dmPolicy: “pairing”` 상태에서는 승인된 사용자만 DM으로 봇을 사용할 수 있습니다. 개인용 봇이라면 이 흐름이 더 안전합니다.

Q4. Windows에서도 설치할 수 있나요?

공식 문서에는 Windows 설치 흐름도 있지만, 처음 설치하고 안정적으로 쓰려면 WSL2 흐름을 권장합니다.

Q5. OpenClaw를 여러 사람이 같이 써도 되나요?

OpenClaw 보안 문서는 하나의 신뢰 경계, 즉 개인 assistant 모델을 전제로 설명합니다. 서로 신뢰하지 않는 여러 사용자가 하나의 tool-enabled agent를 공유하는 구조는 피하고, 필요하다면 gateway와 계정, host를 분리하는 편이 좋습니다.

자료 출처

관련 글로 이어가기

이번 글에서 OpenClaw의 기본 설치와 Telegram DM 연결을 끝냈다면, 다음 단계에서는 Hermes Agent 설치 방법과 OpenClaw에서 Hermes로 넘어갈 때 무엇이 달라지는지 비교해 볼 수 있습니다.