본문 바로가기
AI

OpenClaw Tools & Discord 연결 가이드

by IsaacOth 2026. 2. 7.

OpenClaw Tools & Discord 연결 가이드 - AI 에이전트 확장하기

1. 왜 Tools와 채널 연결이 중요한가?

OpenClaw를 설치했다면, 이제 진짜 마법이 시작됩니다. 기본 상태의 OpenClaw는 "똑똑한 대화 상대"에 불과합니다. 하지만 Tools를 연결하면 실제로 일을 하는 에이전트로 변신합니다.

Tools 연결 전 vs 후 비교:

기능 Tools 없이 Tools 연결 후
파일 읽기/쓰기 ❌ 불가능 ✅ 로컬 파일 직접 수정
웹 검색 ❌ 학습 데이터만 ✅ 실시간 구글 검색
코드 실행 ❌ 불가능 ✅ 터미널 명령어 실행
외부 접속 ❌ 로컬만 ✅ Discord/Slack에서 접근

Discord 연결의 장점:

  • 📱 스마트폰에서 언제든 AI 비서 호출
  • 👥 팀원들과 AI 에이전트 공유
  • 🔔 자동 알림 및 리포트 수신
  • 💻 컴퓨터 앞에 없어도 작업 지시 가능

2. OpenClaw Tools 이해하기

2.1 Tools란 무엇인가?

Tool = AI가 사용할 수 있는 "손"

사람이 손으로 키보드를 치고, 마우스를 클릭하듯이, AI 에이전트는 Tools를 통해 실제 작업을 수행합니다. OpenClaw의 Tools는 크게 세 가지로 나뉩니다:

  1. 빌트인 Tools: 설치하면 바로 쓸 수 있는 기본 도구
  2. Tool Groups: 관련 도구들을 묶어놓은 그룹
  3. Skills: 커뮤니티가 만든 확장 패키지

2.2 빌트인 Tools 상세 설명

OpenClaw에는 다음 도구들이 기본 포함되어 있습니다:

파일 시스템 도구:

  • file: 파일 읽기, 쓰기, 수정, 삭제
  • 예시: "이 폴더의 모든 .txt 파일을 요약해줘"

실행 도구:

  • exec: 터미널 명령어 실행
  • process: 백그라운드 프로세스 관리
  • 예시: "npm install 실행해줘", "현재 실행 중인 프로세스 보여줘"

웹 도구:

  • web_search: 구글 검색 수행
  • web_fetch: 웹페이지 내용 가져오기
  • browser: 실제 브라우저 제어 (스크린샷, 클릭 등)
  • 예시: "오늘 비트코인 시세 검색해줘"

기타 도구:

  • canvas: 다이어그램 생성
  • image: 이미지 처리
  • cron: 예약 작업 설정
  • message: 메시지 전송

2.3 Tool Groups - 한 번에 여러 도구 활성화하기

매번 도구를 하나씩 켜는 것은 번거롭습니다. OpenClaw는 관련 도구들을 그룹으로 묶어서 한 번에 활성화할 수 있게 해줍니다.

그룹 이름 포함된 도구들 용도
group:fs file, 디렉토리 관리 파일 작업
group:web web_search, web_fetch, browser 인터넷 검색
group:runtime exec, process 명령어 실행
group:openclaw 내부 상태 관리 에이전트 제어

2.4 Tools 활성화하는 방법 (상세 가이드)

Tools를 활성화하려면 설정 파일을 수정해야 합니다. 천천히 따라오세요.

Step 1: 설정 파일 위치 찾기

OpenClaw 설정 파일은 다음 위치에 있습니다:

# macOS / Linux
~/.openclaw/openclaw.json

# Windows (WSL2)
/home/사용자이름/.openclaw/openclaw.json

터미널에서 확인:

# 파일 존재 확인
ls -la ~/.openclaw/openclaw.json

# 없으면 빈 설정 파일 생성
mkdir -p ~/.openclaw && echo '{}' > ~/.openclaw/openclaw.json

Step 2: 설정 파일 열기

원하는 편집기로 파일을 엽니다:

# nano 사용 (가장 쉬움)
nano ~/.openclaw/openclaw.json

# VS Code 사용
code ~/.openclaw/openclaw.json

# vim 사용
vim ~/.openclaw/openclaw.json

Step 3: Tools 활성화 설정 추가

아래 내용을 파일에 추가합니다. 이미 내용이 있다면 tools 섹션만 추가하세요:

{
  "tools": {
    "groups": [
      "group:fs",
      "group:web",
      "group:runtime"
    ],
    "enabled": [
      "file",
      "exec",
      "web_search",
      "web_fetch"
    ],
    "disabled": []
  }
}

각 항목 설명:

  • groups: 활성화할 그룹 목록 (그룹 내 모든 도구가 활성화됨)
  • enabled: 개별적으로 활성화할 도구 목록
  • disabled: 특정 도구만 비활성화 (보안상 필요할 때)

Step 4: 설정 적용 확인

저장 후 설정이 제대로 적용되었는지 확인합니다:

openclaw tools list

예상 출력:

Available Tools:
✅ file (group:fs)
✅ exec (group:runtime)
✅ web_search (group:web)
✅ web_fetch (group:web)
✅ browser (group:web)
❌ canvas (disabled)
...

✅ 표시가 된 도구들이 현재 사용 가능한 도구입니다.

Step 5: 실제로 테스트하기

도구가 잘 작동하는지 테스트해봅시다:

# 파일 시스템 테스트
openclaw chat "현재 폴더에 어떤 파일들이 있어?"

# 웹 검색 테스트
openclaw chat "오늘 날씨 검색해줘"

# 명령어 실행 테스트
openclaw chat "현재 시간을 터미널 명령어로 확인해줘"

[IMAGE: openclaw tools list 명령어 실행 결과 - 활성화된 도구들이 체크 표시로 나타남]

2.5 MCP (Model Context Protocol) 연동

MCP는 AI 도구들의 "공용 언어" 같은 것입니다. 다양한 MCP 서버들을 OpenClaw에 연결하면 기능이 무한히 확장됩니다.

MCP 서버 추가 방법:

{
  "mcp": {
    "servers": {
      "filesystem": {
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/directory"]
      },
      "github": {
        "command": "npx",
        "args": ["-y", "@modelcontextprotocol/server-github"],
        "env": {
          "GITHUB_TOKEN": "your_github_token_here"
        }
      }
    }
  }
}

인기 있는 MCP 서버들:

  • @modelcontextprotocol/server-filesystem: 파일 시스템 접근
  • @modelcontextprotocol/server-github: GitHub 연동
  • @modelcontextprotocol/server-slack: Slack 연동
  • @modelcontextprotocol/server-postgres: PostgreSQL 데이터베이스

3. Skills - 커뮤니티 확장팩

3.1 Skills란?

Skills = 누군가 미리 만들어 놓은 "능력 세트"

예를 들어 "YouTube 요약 Skill"을 설치하면, 영상 URL만 주면 자동으로 자막을 가져와서 요약해주는 기능이 추가됩니다.

3.2 Skills 저장 위치

Skills는 두 곳에서 찾습니다:

1. 글로벌 스킬: ~/.openclaw/skills/
2. 프로젝트 스킬: 현재폴더/skills/

프로젝트 스킬이 글로벌보다 우선순위가 높습니다.

3.3 ClawHub에서 Skills 설치하기

ClawHub는 OpenClaw의 앱스토어입니다.

Step 1: 스킬 검색하기

# 터미널에서 검색
clawhub search calendar

# 또는 웹사이트에서 검색
# https://clawhub.com 접속

Step 2: 스킬 설치하기

# 기본 설치
clawhub install google-calendar

# 특정 버전 설치
clawhub install google-calendar@1.2.0

예상 출력:

📦 Installing google-calendar...
✅ Downloaded to ~/.openclaw/skills/google-calendar
✅ Dependencies installed
✅ Skill enabled

To configure, add to your openclaw.json:
{
  "skills": {
    "google-calendar": {
      "enabled": true,
      "apiKey": "YOUR_GOOGLE_API_KEY"
    }
  }
}

Step 3: 스킬 설정하기

설치된 스킬이 API 키를 요구하면 설정 파일에 추가합니다:

{
  "skills": {
    "entries": {
      "google-calendar": {
        "enabled": true,
        "env": {
          "GOOGLE_API_KEY": "your_api_key_here"
        }
      }
    }
  }
}

Step 4: 설치된 스킬 확인

openclaw skills list

예상 출력:

Installed Skills:
✅ google-calendar (v1.2.0) - Google Calendar integration
✅ youtube-summary (v2.0.1) - Summarize YouTube videos
❌ slack-notifier (v1.0.0) - Needs configuration

clawHub : Downloads 순서로 정리. 많은 사람들이 WhatsApp으로 연락을 받는다.

3.4 나만의 Skill 만들기

간단한 스킬은 직접 만들 수 있습니다.

Step 1: 스킬 폴더 생성

mkdir -p ~/.openclaw/skills/my-notifier
cd ~/.openclaw/skills/my-notifier

Step 2: SKILL.md 파일 작성

nano SKILL.md

아래 내용 입력:

---
name: my-notifier
description: "개인 알림 전송 스킬"
version: 1.0.0
author: "내 이름"
requires:
  env:
    - NOTIFIER_WEBHOOK_URL
---

# My Notifier Skill

이 스킬은 중요한 이벤트 발생 시 웹훅으로 알림을 보냅니다.

## 사용 방법

"알림 보내줘: [메시지 내용]" 형식으로 요청하면 됩니다.

## 예시

- "알림 보내줘: 회의 시작 10분 전입니다"
- "긴급 알림: 서버 CPU 사용량 90% 초과"

Step 3: 환경변수 설정

# .env 파일에 추가
echo 'NOTIFIER_WEBHOOK_URL=https://hooks.slack.com/...' >> ~/.openclaw/.env

4. Discord 봇 연결 워크플로우

이제 OpenClaw를 Discord에 연결해서 어디서든 접근할 수 있게 만들어봅시다. 처음이라면 15~20분 정도 걸립니다.

⚠️ 아래 단계는 2026년 Discord Developer Portal UI 기준입니다. 업데이트로 화면이 다를 수 있습니다.

Step 1: Discord Developer Portal 접속

  1. 웹 브라우저를 열고 discord.com/developers/applications 에 접속합니다.
  2. Discord 계정으로 로그인합니다.
    • Discord 계정이 없다면 먼저 discord.com에서 가입하세요.
  3. 로그인 후 "Applications" 페이지가 나타납니다.

Step 2: 새 Application 생성

  1. 화면 오른쪽 상단의 "New Application" 버튼을 클릭합니다.
  2. 팝업창이 뜨면:
    • 이름 입력: OpenClaw-Bot (원하는 이름)
    • 체크박스 선택: "By clicking Create, you agree to the Discord Developer Terms of Service"
    • "Create" 버튼 클릭
  3. Application이 생성되면 General Information 페이지로 이동합니다.

💡 팁: 이름은 나중에 언제든 변경할 수 있습니다.

Step 3: Bot 생성 및 토큰 발급

3-1. Bot 페이지로 이동

  1. 왼쪽 메뉴에서 "Bot" 을 클릭합니다.

3-2. 토큰 생성

  1. "Reset Token" 버튼을 클릭합니다.
    • 처음이라면 "Add Bot" 버튼이 보일 수 있습니다. 클릭하면 됩니다.
  2. 확인 팝업에서 "Yes, do it!" 클릭
  3. 토큰이 표시됩니다!
    • ⚠️ 매우 중요: 이 토큰은 지금 딱 한 번만 볼 수 있습니다!
    • 반드시 "Copy" 버튼을 눌러 복사하세요
    • 메모장이나 비밀번호 관리자에 안전하게 저장하세요

저는 clawdbot->moltbot으로 이름이 바뀌는 도중에 했어서 이름이 이렇습니다.

3-3. 토큰 분실 시

토큰을 잃어버렸다면 "Reset Token"을 다시 눌러 새 토큰을 발급받으면 됩니다. (기존 토큰은 무효화됨)

⚠️ 보안 경고: 토큰은 절대로 GitHub, 블로그, 카카오톡 등에 공유하지 마세요! 토큰이 있으면 누구나 여러분의 봇을 조종할 수 있습니다.

Step 4: Privileged Gateway Intents 활성화

이 단계를 건너뛰면 봇이 메시지를 읽지 못합니다! 가장 많이 하는 실수입니다.

  1. 같은 "Bot" 페이지를 아래로 스크롤합니다.
  2. "Privileged Gateway Intents" 섹션을 찾습니다.
  3. 다음 두 가지를 반드시 ON으로 토글합니다:
Intent 용도 필수 여부
SERVER MEMBERS INTENT 서버 멤버 정보 접근 ✅ 필수
MESSAGE CONTENT INTENT 메시지 내용 읽기 ✅ 필수
  1. 페이지 하단의 "Save Changes" 버튼을 클릭합니다.

⚠️ 주의: 이 설정을 안 하면 봇이 온라인으로 보여도 메시지에 응답하지 않습니다!

Step 5: OpenClaw에 토큰 등록

이제 복사해둔 토큰을 OpenClaw에 알려줄 차례입니다.

방법 1: .env 파일 사용 (권장)

# .env 파일 열기
nano ~/.openclaw/.env

# 아래 줄 추가 (YOUR_TOKEN 부분을 실제 토큰으로 교체)
DISCORD_BOT_TOKEN=YOUR_TOKEN_HERE

# 저장: Ctrl+O, Enter, Ctrl+X

방법 2: 설정 파일에 직접 입력

nano ~/.openclaw/openclaw.json

아래 내용 추가:

{
  "channels": {
    "discord": {
      "enabled": true,
      "token": "YOUR_TOKEN_HERE"
    }
  }
}

설정 확인:

# 토큰이 제대로 등록되었는지 확인
openclaw config get channels.discord.enabled

예상 출력: true

Step 6: 봇을 서버에 초대하기

봇을 만들었으니 이제 여러분의 Discord 서버에 초대해야 합니다.

6-1. OAuth2 URL Generator 이동

  1. 왼쪽 메뉴에서 "OAuth2" 클릭
  2. 하위 메뉴에서 "URL Generator" 클릭

6-2. Scopes 선택

"SCOPES" 섹션에서 다음을 체크:

  • ✅ bot
  • ✅ applications.commands

 

6-3. Bot Permissions 선택

아래로 스크롤하면 "BOT PERMISSIONS" 섹션이 나타납니다. 다음을 체크:

권한 설명
✅ Read Messages/View Channels 채널 보기
✅ Send Messages 메시지 보내기
✅ Send Messages in Threads 스레드에 메시지 보내기
✅ Read Message History 메시지 기록 읽기
✅ Add Reactions 반응 추가
✅ Use Slash Commands 슬래시 명령어 사용

💡 팁: 귀찮으시면 저 처럼 Admin 권한을 주셔도 되는데, 책임은 본인에게 있습니다..!

6-4. 초대 링크 생성 및 사용

  1. 페이지 맨 아래 "GENERATED URL" 섹션을 찾습니다.
  2. "Copy" 버튼을 클릭합니다.
  3. 새 브라우저 탭에 URL을 붙여넣고 Enter

6-5. 서버 선택 및 초대

  1. 드롭다운에서 봇을 초대할 서버 선택
    • 서버 관리자 권한이 있는 서버만 표시됩니다
  2. "계속하기" 클릭
  3. 권한 확인 후 "승인" 클릭
  4. 캡차 완료

Step 7: Gateway 시작 및 테스트

7-1. OpenClaw Gateway 시작

openclaw gateway

예상 출력:

🦞 OpenClaw Gateway starting...
📡 Connecting to Discord...
✅ Discord connected as OpenClaw-Bot#1234
✅ Logged in to 1 server(s)
🚀 Gateway is running. Press Ctrl+C to stop.

7-2. Discord에서 테스트

  1. Discord 앱 또는 웹을 엽니다.
  2. 봇을 초대한 서버로 이동합니다.
  3. 아무 채널에서 봇을 멘션합니다:
@OpenClaw-Bot 안녕! 넌 뭘 할 수 있어?
  1. 봇이 응답하면 성공입니다! 🎉

/status

7-3. 백그라운드 실행 (선택사항)

터미널을 닫아도 봇이 계속 실행되게 하려면:

# 백그라운드로 실행
nohup openclaw gateway > ~/.openclaw/gateway.log 2>&1 &

# 또는 데몬으로 설치 (권장)
openclaw gateway install-daemon

5. Discord 고급 설정

기본 연결이 완료되었다면, 더 세밀한 제어를 해봅시다.

5.1 DM(개인 메시지) 정책 설정

누가 봇에게 DM을 보낼 수 있는지 제어합니다.

{
  "channels": {
    "discord": {
      "enabled": true,
      "token": "YOUR_TOKEN",
      "dm": {
        "policy": "pairing"
      }
    }
  }
}
정책 설명 추천 상황
pairing 페어링 코드 입력한 사용자만 기본값, 가장 안전
allowlist 지정한 사용자 ID만 허용 특정 인원만 사용
open 누구나 DM 가능 공개 서비스용
disabled DM 완전 차단 서버 전용 봇

allowlist 설정 예시:

{
  "channels": {
    "discord": {
      "dm": {
        "policy": "allowlist",
        "allowlist": [
          "123456789012345678",
          "234567890123456789"
        ]
      }
    }
  }
}

💡 사용자 ID 찾는 법: Discord 설정 > 고급 > 개발자 모드 ON > 사용자 우클릭 > ID 복사

5.2 서버(길드)별 설정

서버마다 다른 규칙을 적용할 수 있습니다.

{
  "channels": {
    "discord": {
      "guilds": {
        "1234567890123456789": {
          "requireMention": true,
          "allowedChannels": [
            "9876543210987654321"
          ],
          "prefix": "!"
        }
      }
    }
  }
}
설정 설명
requireMention true면 @멘션해야만 응답
allowedChannels 특정 채널에서만 작동
prefix 멘션 대신 접두사 사용 (예: !질문)

5.3 슬래시 커맨드 활용

OpenClaw는 Discord 네이티브 슬래시 커맨드를 지원합니다.

사용 가능한 기본 명령어:

명령어 기능
/help 도움말 표시
/reset 대화 맥락 초기화
/status 봇 상태 확인
/tools 사용 가능한 도구 목록

채팅창에 /를 입력하면 자동완성으로 명령어 목록이 나타납니다.

6. 이럴 때 유용해요 (Use Cases)

시나리오 1: 팀 개발 비서

상황: 5인 개발팀의 Discord 서버에 OpenClaw 배치

활용 예시:

  • "최근 일주일간 main 브랜치에 머지된 PR 목록 보여줘" → Git 로그 분석
  • "이 에러 로그 분석해줘" → 로그 파일 읽기 + 웹 검색으로 해결책 제시
  • "오늘 스탠드업 회의록 요약해서 #공지 채널에 올려줘" → 메시지 기록 분석 + 전송

시나리오 2: 개인 생산성 비서

상황: 나만의 비밀 Discord 서버를 대시보드로 사용

활용 예시:

  • "오전 9시마다 뉴스 요약해서 여기 올려줘" → cron + web_search + message
  • "이 PDF 요약해서 보내줘" → file + 요약 + message
  • "~/Downloads 폴더 정리해줘" → file 시스템 작업

시나리오 3: 커뮤니티 서포트 봇

상황: 오픈소스 프로젝트의 Discord 서버

활용 예시:

  • 자주 묻는 질문에 자동 응답
  • 새 이슈 등록 시 GitHub에서 정보 가져와서 요약
  • 문서 링크 검색해서 제공

7. 팁과 Best Practices

  • 💡 팁 1: 보안 - exec 도구 제한하기
    • 공개 서버에서는 exec 도구를 비활성화하거나 허용 명령어를 제한하세요. 
      {
"tools": {
  "disabled": ["exec"]
}
}
  • 💡 팁 2: 성능 - 필요한 도구만 활성화
    • 브라우저 도구는 메모리를 많이 사용합니다. 필요할 때만 켜세요.
  • 💡 팁 3: 비용 - 저렴한 모델 사용
    • Discord 일상 대화에는 Claude Sonnet이나 GPT-4o-mini처럼 저렴한 모델을 사용하세요.
  • 💡 팁 4: 토큰 - 환경변수로 관리
    • 설정 파일에 토큰을 직접 쓰지 말고 .env 파일을 사용하세요.
  • 💡 팁 5: 로그 - 문제 발생 시 확인
    • 봇이 이상하게 동작하면 ~/.openclaw/logs/ 폴더를 확인하세요. 
      tail -f ~/.openclaw/logs/gateway.log
  • ⚠️ 주의: 24시간 운영하려면
    • OpenClaw는 로컬에서 실행됩니다. 컴퓨터가 꺼지면 봇도 오프라인!
    • 상시 운영이 필요하다면 라즈베리파이, 미니 PC, 또는 클라우드 서버를 고려하세요.

8. 트러블슈팅

오류 1: 봇이 온라인인데 응답 안함

증상: Discord에서 봇이 초록색(온라인)인데 메시지에 반응 없음

원인 & 해결:

  1. Intent 설정 확인 (가장 흔함)
    • Discord Developer Portal > Bot > MESSAGE CONTENT INTENT가 ON인지 확인
    • 변경 후 Save Changes 눌렀는지 확인
  2. 채널 권한 확인
    • 봇이 해당 채널에서 메시지를 읽을 권한이 있는지 확인
    • 채널 설정 > 권한 > OpenClaw-Bot 역할 확인
  3. Gateway 재시작
  4. # 기존 프로세스 종료 pkill -f "openclaw gateway" # 다시 시작 openclaw gateway

오류 2: "Invalid Token" 에러

증상: Gateway 시작 시 토큰 오류 발생

해결:

  1. 토큰 앞뒤 공백 확인:
  2. cat ~/.openclaw/.env | grep DISCORD # 출력: DISCORD_BOT_TOKEN=ABC123... (앞뒤에 공백이나 따옴표 없어야 함)
  3. 토큰 재발급:
    • Discord Developer Portal > Bot > Reset Token
    • 새 토큰으로 .env 파일 업데이트

오류 3: 봇 초대 안됨

증상: 초대 링크 클릭해도 서버 목록이 비어있음

해결:

  1. 서버 관리자 권한이 있는지 확인
  2. 서버 설정 > 역할 > 본인 역할에 "서버 관리" 권한 있는지 확인
  3. OAuth2 URL Generator에서 bot scope가 체크되어 있는지 확인

오류 4: Tools가 작동 안함

증상: "파일 읽어줘" 같은 요청에 "해당 도구가 없습니다" 응답

해결:

  1. Tools 활성화 상태 확인:
  2. openclaw tools list
  3. 설정 파일에 tools 섹션이 있는지 확인:
  4. cat ~/.openclaw/openclaw.json | grep -A 10 tools
  5. 설정 파일 문법 오류 확인:
  6. # JSON 문법 검사 python3 -m json.tool ~/.openclaw/openclaw.json

9. 다음 단계

축하합니다! 🎉 이제 OpenClaw가 Discord에서 작동합니다.

더 나아가려면:

  • 다른 채널 연결: WhatsApp, Telegram, Slack도 비슷한 방식으로 연결 가능
  • 자동화 강화: n8n, Zapier와 연동하여 복잡한 워크플로우 구축
  • 커스텀 Skills 개발: 나만의 자동화 로직 만들기
  • 팀 배포: Docker로 패키징하여 팀 서버에 배포

10. TL;DR

  • Tools는 OpenClaw에게 파일 읽기, 웹 검색, 명령어 실행 능력을 부여합니다.
  • 설정 파일(~/.openclaw/openclaw.json)에서 group:fs, group:web, group:runtime을 추가하면 활성화됩니다.
  • Discord 연결 핵심 3단계: ① Bot 토큰 발급 → ② MESSAGE CONTENT INTENT 켜기 → ③ 서버 초대
  • Skills는 ClawHub에서 clawhub install [이름]으로 설치합니다.
  • 봇이 응답 안 하면 99% Intent 설정 문제입니다!

11. 참고 링크

'AI' 카테고리의 다른 글

Kimi K2.5 에이전트 아키텍처 완벽 해부 1편 - 설계 철학과 인프라  (0) 2026.02.08
2026년 로컬 OCR 벤치마크 - GLM, DeepSeek, LightOn, Paddle, Apple ML 완벽 비교  (0) 2026.02.08
OpenClaw 상세 설치 가이드 - 초보자용  (0) 2026.02.06
2026년 2월 신규모델 Claude Opus 4.6 & GPT-5.3 Codex  (1) 2026.02.06
[4편] CliProxyAPI 완벽 가이드 - CLI AI 모델을 표준 API로 통합하기  (0) 2026.02.06

관련글

티스토리툴바