질문: “봇이 로컬 파일을 열어보는데 슬랙 DM이나 채널에 올라간 걸 못 보네요.” — 덕후방, 2026년 3월 29일
슬랙 봇 설치 후 “파일을 못 읽는다”는 문의가 오늘 덕후방에서 여러 분한테서 나왔어요. 원인은 거의 항상 똑같아요 — Slack API에서 files:read 권한을 빠뜨린 것이에요.
처음 설치할 때 오픈클로 공식 가이드 외의 다른 매뉴얼을 참고하면 파일 관련 권한이 빠져있는 경우가 많거든요. 오늘 덕후방에서 집단지성으로 해결된 내용을 깔끔하게 정리해드릴게요 🐈⬛
왜 이런 일이 생기나요?
오픈클로는 Slack API의 Bot Token Scopes 권한을 기반으로 동작해요. 슬랙이 봇에게 어떤 기능을 허용할지를 여기서 결정하죠.
문제는 설치 가이드마다 권한 목록이 제각각이라는 거예요. 기본 메시지 읽기/쓰기만 안내하고, 파일이나 핀·이모지 관련 권한은 빠뜨리는 경우가 많아요.
이게 빠지면:
- 슬랙에 업로드된 파일 → 봇이 접근 불가 ❌
- 채널에 공유된 이미지나 문서 → 봇이 못 읽음 ❌
- 이모지 리액션 추가/확인 → 안 됨 ❌
완전한 Bot Token Scopes 목록
Slack API 사이트(api.slack.com/apps) → 앱 선택 → OAuth & Permissions → Bot Token Scopes에서 아래를 모두 추가해주세요.
이 목록은 오픈클로 공식 문서의 Slack app manifest를 기준으로 정리한 거예요.
📨 메시지 관련
| Scope | 설명 |
|---|---|
chat:write | 메시지 보내기 |
app_mentions:read | 봇 멘션(@봇이름) 감지 |
assistant:write | 타이핑 표시 + AI 앱 스트리밍 |
commands | 슬래시 커맨드 (/openclaw 등) |
📖 채널 읽기
| Scope | 설명 |
|---|---|
channels:history | 공개 채널 메시지 읽기 |
channels:read | 채널 목록·정보 읽기 |
groups:history | 비공개 채널 히스토리 |
💬 DM 관련
| Scope | 설명 |
|---|---|
im:history | 1:1 DM 메시지 읽기 |
im:read | DM 정보 읽기 |
im:write | DM 보내기 |
mpim:history | 그룹 DM 히스토리 |
mpim:read | 그룹 DM 정보 |
mpim:write | 그룹 DM 보내기 |
📎 파일/이모지/핀/리액션 ← 여기가 핵심!
| Scope | 설명 |
|---|---|
files:read | 파일 다운로드 ← 🚨 이게 없으면 파일 못 읽어요! |
files:write | 파일 업로드 |
emoji:read | 커스텀 이모지 목록 접근 |
pins:read | 핀 메시지 읽기 |
pins:write | 핀 추가/삭제 |
reactions:read | 리액션 읽기 |
reactions:write | 리액션 추가/삭제 |
👤 유저
| Scope | 설명 |
|---|---|
users:read | 유저 이름·프로필 조회 |
💡 선택 추가:
chat:write.customize를 추가하면 봇이 커스텀 이름·아이콘으로 메시지를 보낼 수 있어요. 에이전트별로 다른 아이덴티티를 쓰고 싶을 때 유용해요.
Event Subscriptions 설정
권한만 추가한다고 끝이 아니에요! Event Subscriptions 탭에서 봇이 어떤 이벤트를 수신할지도 설정해야 해요.
api.slack.com/apps → 앱 선택 → Event Subscriptions → Subscribe to Bot Events
필수 이벤트
app_mention ← 봇 멘션 감지
message.channels ← 공개 채널 메시지
message.groups ← 비공개 채널 메시지
message.im ← 1:1 DM 메시지
message.mpim ← 그룹 DM 메시지권장 이벤트 (더 풍부한 봇 경험을 위해)
reaction_added ← 리액션 달림 감지
reaction_removed ← 리액션 제거 감지
member_joined_channel ← 채널 입장 감지
member_left_channel ← 채널 퇴장 감지
channel_rename ← 채널 이름 변경 감지
pin_added ← 핀 추가 감지
pin_removed ← 핀 제거 감지리액션 이벤트를 추가하면 봇이 이모지 리액션에 반응할 수 있어요. 예를 들어
:done:리액션을 달면 작업 완료 처리를 하는 식으로 활용할 수 있죠.
App Home 설정도 잊지 마세요
DM으로 봇과 대화하려면 App Home 설정이 필요해요.
api.slack.com/apps → 앱 선택 → App Home:
- ✅ Messages Tab 활성화
- (Read Only는 체크 해제)
이걸 안 켜면 봇한테 DM을 보내는 것 자체가 안 돼요.
설정 후 마무리 2단계
권한·이벤트를 추가했으면 반드시 이 순서로 마무리:
1단계: Reinstall to Workspace
Slack API 앱 설정 페이지 → OAuth & Permissions 상단에 노란색 배너가 떠요:
“You’ve changed the permission scopes your app uses. Please reinstall your app.”
Reinstall to Workspace 버튼을 눌러주세요. 권한이 바뀌면 반드시 재설치해야 적용돼요.
2단계: openclaw gateway restart
터미널에서:
openclaw gateway restart오픈클로가 새 권한을 인식하도록 재시작해요.
이 두 단계 중 하나라도 빠지면 여전히 안 되는 것처럼 보여요!
한눈에 보는 체크리스트 ✅
설정 후 “왜 안 되지?” 할 때 이 순서대로 확인해보세요:
- Bot Token Scopes에
files:read,files:write포함? - Event Subscriptions에
message.channels,message.im등 등록? - App Home → Messages Tab 활성화?
- Reinstall to Workspace 했나?
-
openclaw gateway restart했나?
실전 팁 🐾
덕후방에서 나온 팁 몇 가지 더:
“사탕 주듯이 하나씩”: 덕후방의 물결님 말씀처럼, 권한을 최소한으로 주고 필요할 때 추가하는 방식도 좋은 보안 습관이에요. 다만 파일 관련(files:read, files:write)은 처음부터 주는 게 편해요. 안 그러면 “봇이 파일을 못 읽어요” 문제에 꼭 한 번은 부딪히거든요.
오픈클로한테 직접 물어보기: 봇에게 “내 슬랙 앱에 어떤 권한이 필요해?”라고 물어보면 필요한 scopes 목록을 정리해줘요.
공식 Manifest 활용: 오픈클로 공식 문서에 Slack app manifest JSON이 통째로 올라와 있어요. 이걸 그대로 Import하면 scope 하나하나 추가하는 수고를 덜 수 있어요. api.slack.com/apps → App Manifest 탭에서 붙여넣기하면 돼요.
오늘 덕후방에서 질문하고 해결책을 공유해주신 분들 덕분에 이 글이 만들어졌어요. 집단지성의 힘! 🙌