Slack 연동 가이드

협업 툴에 봇을 연동하는 일은 생각보다 까다로워요. 메시지를 주고받는 방식부터 권한 설정까지 챙길 게 한두 개가 아니거든요. 설정 과정에서 길을 잃지 않도록 Slack을 빠르고 정확하게 연결하는 방법을 정리해 드릴게요.

필요한 것

Slack App (Socket Mode 또는 HTTP Mode 지원)
App Token (connections:write 권한 포함)
Bot Token (xoxb- 접두사)
Slack Signing Secret (HTTP Mode 사용 시 필요)

빠른 시작

OpenClaw는 기본적으로 Socket Mode를 사용하며, HTTP Events API 방식도 지원해요. 5분 안에 설정을 마칠 수 있도록 단계를 나누어 설명할게요.

Socket Mode (기본값):

1. Slack App 및 토큰 생성

Slack App 설정에서 다음 작업을 수행하세요.

Socket Mode를 활성화하세요.
connections:write 권한이 포함된 App Token(xapp-...)을 생성하세요.
App을 설치하고 Bot Token(xoxb-...)을 복사하세요.

2. OpenClaw 설정

{
  channels: {
    slack: {
      enabled: true,
      mode: "socket",
      appToken: "xapp-...",
      botToken: "xoxb-...",
    },
  },
}

환경 변수를 사용할 수도 있어요 (기본 계정 전용):

SLACK_APP_TOKEN=xapp-...
SLACK_BOT_TOKEN=xoxb-...

3. App 이벤트 구독

다음 Bot 이벤트를 구독하세요.

app_mention
message.channels, message.groups, message.im, message.mpim
reaction_added, reaction_removed
member_joined_channel, member_left_channel
channel_rename
pin_added, pin_removed

DM 사용을 위해 App Home에서 Messages Tab도 활성화해야 해요.

4. Gateway 시작

openclaw gateway

HTTP Events API 모드:

5. HTTP를 위한 Slack App 설정

모드를 HTTP로 설정하세요 (channels.slack.mode="http")
- Slack Signing Secret을 복사하세요.
- Event Subscriptions, Interactivity, Slash command의 Request URL을 모두 동일한 webhook 경로(기본값 /slack/events)로 설정하세요.
6. OpenClaw HTTP 모드 설정
섹션 제목: “6. OpenClaw HTTP 모드 설정”

{
  channels: {
    slack: {
      enabled: true,
      mode: "http",
      botToken: "xoxb-...",
      signingSecret: "your-signing-secret",
      webhookPath: "/slack/events",
    },
  },
}

7. 다중 계정 HTTP를 위한 고유 Webhook 경로 사용

계정별 HTTP 모드를 지원해요.

설정이 충돌하지 않도록 각 계정에 서로 다른 webhookPath를 부여하세요.

문제 해결

연동 과정에서 문제가 발생하면 다음 내용을 확인해 보세요.

채널 진단: 채널 간 진단 및 복구 플레이북을 확인하세요.
권한 확인: App Token에 connections:write 권한이 올바르게 부여되었는지 다시 보세요.

설정 과정에서 도움이 더 필요하다면 AI Setup Assistant에게 물어보세요.

다음 단계

Pairing: Slack DM 기본 페어링 모드 알아보기
Slash commands: 네이티브 커맨드 동작 및 카탈로그 확인하기

새로운 Slack 앱을 개발할 때 가장 먼저 마주하는 난관은 인증과 권한 설정이에요. 토큰 종류는 왜 이렇게 많고, 어떤 상황에 어떤 토큰을 써야 하는지 헷갈릴 때가 많죠. 설정 하나만 어긋나도 메시지가 전송되지 않거나 보안 이슈가 생길 수 있어 늘 신경 쓰이는 부분입니다.

복잡해 보이는 Slack 인증 구조를 명확하게 정리해 드릴게요. 토큰 모델부터 채널 접근 제어까지, 설정을 최적화하는 방법을 함께 살펴보겠습니다.

필요한 것

Slack API 앱 자격 증명 (botToken, appToken 또는 signingSecret)
환경 변수 설정 권한 (SLACK_BOT_TOKEN, SLACK_APP_TOKEN)
프로젝트 구성 파일 수정 권한

빠른 시작

Slack 앱의 연결 방식과 권한 모델을 5분 만에 설정하는 핵심 내용입니다.

1. Token model 선택하기

연결 모드에 따라 필요한 토큰 조합이 달라집니다.

Socket Mode: botToken과 appToken이 모두 필요해요.
HTTP mode: botToken과 signingSecret 조합을 사용하세요.

토큰 설정 시 우선순위와 규칙을 기억하세요:

구성 파일에 직접 입력한 토큰은 환경 변수(env fallback) 설정보다 우선합니다.
SLACK_BOT_TOKEN과 SLACK_APP_TOKEN 환경 변수는 기본 계정에만 적용돼요.
userToken (xoxp-...)은 구성 파일에서만 설정할 수 있으며, 기본적으로 읽기 전용(userTokenReadOnly: true)으로 작동합니다.

Tip: 액션이나 디렉토리 정보를 읽을 때는 userToken을 사용하는 것이 좋지만, 메시지를 쓸 때는 botToken을 권장해요. userToken으로 메시지를 쓰려면 userTokenReadOnly: false로 설정되어 있어야 하고, botToken을 사용할 수 없는 상태여야 합니다.

2. DM 및 채널 액세스 제어

channels.slack.dm.policy를 통해 DM 접근 방식을 결정할 수 있어요.

pairing (기본값)
allowlist
open (dm.allowFrom에 "*"가 포함되어야 해요)
disabled

DM 관련 세부 플래그는 다음과 같습니다:

dm.enabled: 기본값은 true입니다.
dm.allowFrom: 접근 허용 대상을 지정합니다.
dm.groupEnabled: 그룹 DM 허용 여부이며 기본값은 false입니다.
dm.groupChannels: 선택 사항으로 MPIM allowlist를 설정합니다.

DM 페어링을 승인하려면 다음 명령어를 사용하세요:

openclaw pairing approve slack <code>

3. 채널 정책 및 멘션 설정

channels.slack.groupPolicy는 채널 핸들링 방식을 제어해요. open, allowlist, disabled 중 선택할 수 있으며, allowlist 항목은 channels.slack.channels 아래에 정의합니다.

채널 메시지는 기본적으로 멘션이 있어야 반응하며, 소스는 다음과 같습니다:

앱 직접 멘션 (<@botId>)
멘션 정규표현식 패턴 (agents.list[].groupChat.mentionPatterns)
스레드 내 암시적 답장

문제 해결

설정 중 발생할 수 있는 일반적인 문제와 해결 방법입니다.

토큰 우선순위 문제: 환경 변수를 설정했는데 반영되지 않는다면, 구성 파일에 직접 입력된 토큰이 있는지 확인해 보세요. 구성 파일 설정이 항상 우선합니다.
userToken 쓰기 권한: userToken으로 메시지가 보내지지 않는다면 userTokenReadOnly: false 설정이 누락되었거나 botToken이 활성화되어 있는지 체크하세요.
런타임 경고 발생: channels.slack 설정이 아예 없고 환경 변수만 사용하는 상태에서 channels.defaults.groupPolicy를 정하지 않았다면, 시스템은 groupPolicy="open"으로 작동하며 경고 로그를 남깁니다.
이름/ID 확인 실패: 시작 시 토큰 권한이 부족하면 allowlist의 항목을 확인하지 못할 수 있어요. 이 경우 확인되지 않은 항목은 설정된 그대로 유지됩니다.

더 자세한 설정 방법이나 도움이 필요하다면 AI Setup Assistant에게 물어보세요.

다음 단계

슬랙 앱을 개발하다 보면 사용자가 입력하는 슬래시(/) 명령어 처리가 생각만큼 매끄럽지 않아 당황할 때가 있죠. 특히 네이티브 명령어와 커스텀 Slash Command 사이에서 설정이 꼬이면 사용자 경험이 뚝 떨어지곤 합니다.

명령어 응답이 늦어지거나 스레드 처리가 예상과 다르게 동작하는 상황은 개발자라면 누구나 겪는 고민이에요. 이런 부분들을 어떻게 깔끔하게 구성할 수 있는지 핵심 설정들을 정리해 드릴게요.

필요한 것

이 가이드를 따라하기 위해 다음 내용이 필요해요.

Slack App 설정 권한
channels.slack 설정을 수정할 수 있는 환경

빠른 시작

5분 안에 Slack 명령어를 활성화하는 방법이에요.

네이티브 명령어 활성화: Slack의 네이티브 명령어 모드는 기본적으로 off 상태입니다. channels.slack.commands.native: true (또는 글로벌 commands.native: true)를 설정하세요.
명령어 등록: 네이티브 명령어를 활성화했다면, Slack 관리자 페이지에서 일치하는 Slash Command(/<command> 이름)를 등록해야 합니다.
단일 명령어 사용: 네이티브 명령어를 쓰지 않는다면 channels.slack.slashCommand를 통해 설정된 단일 Slash Command만 실행할 수 있어요.

기본 Slash Command 설정값:

enabled: false
name: "openclaw"
sessionPrefix: "slack:slash"
ephemeral: true

Threading, sessions, and reply tags

Slack의 메시지 유형에 따라 세션 라우팅 방식이 달라져요. DM은 direct, 채널은 channel, MPIM은 group으로 라우팅됩니다.

세션 구조: 기본적으로 session.dmScope=main 설정 시 Slack DM은 에이전트의 메인 세션으로 통합됩니다. 채널 세션은 agent:<agentId>:slack:channel:<channelId> 형식을 따릅니다.
스레드 세션: 스레드 답글은 필요한 경우 :thread:<threadTs> 접미사가 붙어 별도 세션으로 생성될 수 있어요.
답장 모드 제어: channels.slack.replyToMode를 통해 off, first, all 중 선택할 수 있으며(기본값 off), 채팅 타입별로 설정하고 싶다면 channels.slack.replyToModeByChatType을 사용하세요.

수동 답장 태그도 지원합니다:

[[reply_to_current]]
[[reply_to:<id>]]

Media, chunking, and delivery

Slack과 주고받는 미디어와 텍스트 처리 방식입니다.

Inbound attachments

Slack 파일 첨부물은 Slack에서 호스팅하는 프라이빗 URL을 통해 다운로드됩니다. 토큰 인증 흐름을 거치며, 용량 제한 내에서 성공적으로 가져오면 미디어 스토어에 저장돼요.

기본 인바운드 크기 제한: 20MB (필요 시 channels.slack.mediaMaxMb로 변경 가능)

Outbound text and files

텍스트 청크: channels.slack.textChunkLimit을 사용하며 기본값은 4000자입니다.
청크 모드: channels.slack.chunkMode="newline"을 설정하면 단락 우선순위로 텍스트를 나눕니다.
파일 전송: Slack 업로드 API를 사용하며 thread_ts를 포함해 스레드 답글로 보낼 수 있습니다.

Delivery targets

명시적인 타겟 지정이 필요할 때 다음 형식을 권장해요.

DM 전송: user:<id>
채널 전송: channel:<id>

Actions and gates

Slack 액션은 channels.slack.actions.* 설정을 통해 제어됩니다. 현재 Slack 툴링에서 사용 가능한 액션 그룹은 다음과 같아요.

Group	Default
messages	enabled
reactions	enabled
pins	enabled
memberInfo	enabled
emojiList	enabled

Events and operational behavior

다양한 Slack 이벤트들이 시스템 이벤트로 매핑되어 처리됩니다.

메시지 수정/삭제 및 스레드 브로드캐스트
리액션 추가/제거
멤버 참여/퇴장, 채널 생성/이름 변경, 핀 추가/제거
채널 변경: configWrites가 활성화된 경우 channel_id_changed 이벤트를 통해 채널 설정 키를 마이그레이션할 수 있습니다.
컨텍스트: 채널의 주제(topic)나 목적(purpose) 메타데이터는 신뢰할 수 없는 컨텍스트로 취급되어 라우팅 컨텍스트에 주입될 수 있어요.

문제 해결

설정 과정에서 문제가 생기면 다음 사항을 확인해 보세요.

명령어가 작동하지 않나요?: commands.native: "auto" 설정으로는 Slack 네이티브 명령어가 활성화되지 않습니다. 반드시 channels.slack.commands.native: true를 명시적으로 설정했는지 확인하세요.
파일 업로드가 실패하나요?: 파일 크기가 20MB를 초과했는지 확인해 보세요. 용량을 늘려야 한다면 channels.slack.mediaMaxMb 옵션을 조정해야 합니다.
Slash Command 세션 격리: Slash 세션은 agent:<agentId>:slack:slash:<userId>와 같은 격리된 키를 사용하지만, 실행은 여전히 대상 대화 세션(CommandTargetSessionKey)을 기준으로 라우팅됩니다.

궁금한 점이 더 있다면 AI Setup Assistant에게 물어보세요!

다음 단계

Slack 앱을 연동하다 보면 권한 설정 때문에 막힐 때가 많아요. 분명 설정을 다 마친 것 같은데 특정 API가 작동하지 않아 당황스럽기도 하죠. 번거로운 과정 없이 한 번에 설정을 끝낼 수 있도록 가이드를 준비했어요.

필요한 것

Slack App Manifest 예시
Bot 및 User Token 권한(Scope) 목록

빠른 시작

5분 만에 설정을 끝내는 방법이에요. 아래의 Manifest JSON 예시를 복사해서 Slack App 설정의 Manifest 탭에 붙여넣으세요. OpenClaw를 기준으로 구성된 예시입니다.

{
  "display_information": {
    "name": "OpenClaw",
    "description": "Slack connector for OpenClaw"
  },
  "features": {
    "bot_user": {
      "display_name": "OpenClaw",
      "always_online": false
    },
    "app_home": {
      "messages_tab_enabled": true,
      "messages_tab_read_only_enabled": false
    },
    "slash_commands": [
      {
        "command": "/openclaw",
        "description": "Send a message to OpenClaw",
        "should_escape": false
      }
    ]
  },
  "oauth_config": {
    "scopes": {
      "bot": [
        "chat:write",
        "channels:history",
        "channels:read",
        "groups:history",
        "im:history",
        "mpim:history",
        "users:read",
        "app_mentions:read",
        "reactions:read",
        "reactions:write",
        "pins:read",
        "pins:write",
        "emoji:read",
        "commands",
        "files:read",
        "files:write"
      ]
    }
  },
  "settings": {
    "socket_mode_enabled": true,
    "event_subscriptions": {
      "bot_events": [
        "app_mention",
        "message.channels",
        "message.groups",
        "message.im",
        "message.mpim",
        "reaction_added",
        "reaction_removed",
        "member_joined_channel",
        "member_left_channel",
        "channel_rename",
        "pin_added",
        "pin_removed"
      ]
    }
  }
}

문제 해결

읽기 작업 권한이 부족한 경우

channels.slack.userToken을 구성했는데 읽기 작업이 제대로 실행되지 않는다면, 아래의 User-token Scope가 설정되어 있는지 확인해 보세요.

channels:history, groups:history, im:history, mpim:history
channels:read, groups:read, im:read, mpim:read
users:read
reactions:read
pins:read
emoji:read
search:read (Slack 검색 읽기 기능에 의존하는 경우)

설정 과정에서 도움이 더 필요하다면 AI Setup Assistant에게 질문해 주세요.

다음 단계

---
title: Slack 연동 문제 해결하기
description: Slack 채널이나 DM에서 메시지 응답이 없을 때 체크해야 할 리스트와 설정 가이드입니다.
---

슬랙 봇을 연동했는데 메시지가 오지 않으면 정말 답답하죠? 분명 설정을 다 마친 것 같은데 반응이 없을 때, 어디서부터 손을 대야 할지 막막한 경험이 다들 있을 거예요. 설정 파일의 작은 옵션 하나나 Slack API 설정 문제로 연결이 꼬이는 경우가 많습니다.

이 글에서는 Slack 연동 시 발생하는 주요 문제들을 빠르게 진단하고 해결하는 방법을 정리했습니다.

## 필요한 것

문제를 해결하기 위해 다음 항목들이 준비되어 있어야 합니다.

- Slack app 설정 (botToken, appToken, signingSecret)
- OpenClaw CLI
- Socket Mode 또는 HTTP Mode 활성화 상태

## 빠른 시작

문제가 발생했을 때 가장 먼저 실행해 봐야 하는 5분 진단 경로입니다. 아래 명령어들을 통해 현재 상태를 빠르게 파악할 수 있어요.

1. **상태 진단**: `openclaw doctor` 명령어로 전체적인 설정 오류를 확인하세요.
2. **로그 모니터링**: `openclaw logs --follow`를 실행해 실시간으로 들어오는 이벤트를 확인하세요.
3. **채널 상태 체크**: `openclaw channels status --probe`로 각 채널의 연결 상태를 점검하세요.

## 문제 해결

### 채널에서 응답이 없는 경우
채널에서 봇이 반응하지 않는다면 다음 항목들을 순서대로 체크해 보세요.

- `groupPolicy` 설정 확인
- 채널 허용 리스트 (`channels.slack.channels`) 확인
- `requireMention` 설정 확인 (멘션이 필수인지 여부)
- 채널별 `users` 허용 리스트

진단에 유용한 명령어:
```bash
openclaw channels status --probe
openclaw logs --follow
openclaw doctor

DM 메시지가 무시되는 경우

DM(Direct Message)이 작동하지 않는다면 다음 설정을 확인해야 합니다.

channels.slack.dm.enabled가 활성화되어 있는지 확인
channels.slack.dm.policy 설정 확인
페어링 승인 또는 허용 리스트(allowlist) 항목 확인

페어링 목록 확인 명령어:

openclaw pairing list slack

Socket Mode 연결 실패

Socket Mode가 연결되지 않는다면 Slack app settings에서 다음 항목을 검증하세요.

botToken 및 appToken이 정확한지 확인
Slack app 설정에서 Socket Mode가 활성화(Enablement)되어 있는지 확인

HTTP Mode에서 이벤트를 받지 못하는 경우

HTTP Mode를 사용 중인데 이벤트가 오지 않는다면 다음을 체크하세요.

signing secret 값 검증
webhook path 설정 확인
Slack Request URLs (Events, Interactivity, Slash Commands) 설정 확인
HTTP 계정당 고유한 webhookPath가 할당되었는지 확인

Native/Slash Command가 작동하지 않는 경우

명령어가 실행되지 않는다면 의도한 모드가 무엇인지 먼저 확인하세요.

Native command mode: Slack에 개별 슬래시 커맨드를 등록하고 channels.slack.commands.native: true로 설정했는지 확인
Single slash command mode: channels.slack.slashCommand.enabled: true 설정을 사용 중인지 확인

추가로 commands.useAccessGroups 설정과 채널/사용자 허용 리스트를 함께 점검해 보세요.

Configuration reference pointers

설정을 수정할 때 참고해야 할 주요 항목들입니다.

주요 참조 문서:

Configuration reference - Slack

주요 Slack 설정 필드:

Mode/Auth: mode, botToken, appToken, signingSecret, webhookPath, accounts.*
DM Access: dm.enabled, dm.policy, dm.allowFrom, dm.groupEnabled, dm.groupChannels
Channel Access: groupPolicy, channels.*, channels.*.users, channels.*.requireMention
Threading/History: replyToMode, replyToModeByChatType, thread.*, historyLimit, dmHistoryLimit, dms.*.historyLimit
Delivery: textChunkLimit, chunkMode, mediaMaxMb
Ops/Features: configWrites, commands.native, slashCommand.*, actions.*, userToken, userTokenReadOnly

해결되지 않는 문제가 있다면 AI Setup Assistant에게 질문해 보세요.

다음 단계

OpenClaw Expert

아직 막혀 있나요?

이 문서에서 답을 못 찾았다면 OpenClaw Expert에게 바로 물어보세요.

Slack 연동 가이드

필요한 것

빠른 시작

1. Slack App 및 토큰 생성

2. OpenClaw 설정

3. App 이벤트 구독

4. Gateway 시작

5. HTTP를 위한 Slack App 설정

6. OpenClaw HTTP 모드 설정

7. 다중 계정 HTTP를 위한 고유 Webhook 경로 사용

문제 해결

다음 단계

필요한 것

빠른 시작

1. Token model 선택하기

2. DM 및 채널 액세스 제어

3. 채널 정책 및 멘션 설정

문제 해결

다음 단계

필요한 것

빠른 시작

Threading, sessions, and reply tags

Media, chunking, and delivery

Inbound attachments

Outbound text and files

Delivery targets

Actions and gates

Events and operational behavior

문제 해결

다음 단계

필요한 것

빠른 시작

문제 해결

읽기 작업 권한이 부족한 경우

다음 단계

DM 메시지가 무시되는 경우

Socket Mode 연결 실패

HTTP Mode에서 이벤트를 받지 못하는 경우

Native/Slash Command가 작동하지 않는 경우

Configuration reference pointers

다음 단계

아직 막혀 있나요?