​

Slack

​

빠른 설정 가이드

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

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

openclaw gateway

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

​

토큰 모델 및 권한

• 소켓 모드: botToken + appToken 필수.
• HTTP 모드: botToken + signingSecret 필수.
• 설정 파일의 토큰은 환경 변수 설정보다 우선함.
• userToken (xoxp-...)은 설정 파일에서만 지정 가능하며, 기본적으로 읽기 전용(userTokenReadOnly: true)임.
• 아이덴티티 커스터마이징: 발신 메시지에 에이전트 고유의 이름과 아이콘을 사용하려면 chat:write.customize 권한을 추가함.

​

접근 제어 및 라우팅

​

DM 정책

• pairing (기본값): 승인 전까지 메시지 무시.
• allowlist: 지정된 사용자만 허용.
• open: 모든 사용자 허용 (allowFrom: ["*"] 필요).
• disabled: DM 기능 비활성화.

• dm.enabled (기본값 true)
• channels.slack.allowFrom (권장)
• dm.allowFrom (legacy)
• dm.groupEnabled (그룹 DM은 기본 false)
• dm.groupChannels (선택적 MPIM allowlist)

• channels.slack.accounts.default.allowFrom은 default 계정에만 적용됨.
• 이름 있는 계정은 자체 allowFrom이 없을 때 channels.slack.allowFrom을 상속함.
• 이름 있는 계정은 channels.slack.accounts.default.allowFrom을 상속하지 않음.

​

채널 정책

• open: 모든 채널 메시지 수락. (멘션 게이팅은 유지됨)
• allowlist: channels.slack.channels에 등록된 채널만 허용.
• 이름 해석: 시작 시 채널명이나 사용자명을 실제 ID로 자동 변환함. 정확한 매칭이 필요할 경우 dangerouslyAllowNameMatching: true 설정이 필요함.

• channels.slack 블록이 완전히 없으면, env-only 설정에서도 런타임은 groupPolicy="allowlist"로 폴백하고 경고를 남김.
• 채널 allowlist와 DM allowlist 항목은 토큰 접근이 가능하면 시작 시 ID로 해석함.
• 해석되지 않은 항목은 설정한 값 그대로 유지됨.

​

멘션 및 사용자 필터링

• 앱 직접 멘션 (<@봇ID>)
• 정규표현식 패턴 매칭 (mentionPatterns)
• 봇의 답변에 대한 스레드 답장

• requireMention
• users
• allowBots
• skills
• systemPrompt
• tools, toolsBySender

​

명령어와 slash 동작

• Slack에서는 native command auto-mode가 기본적으로 꺼져 있음. commands.native: "auto"만으로는 Slack native commands가 활성화되지 않음.
• channels.slack.commands.native: true 또는 전역 commands.native: true로 native handlers를 켤 수 있음.
• native commands를 쓸 때는 Slack에 대응하는 slash commands(/<command>)를 등록해야 하며, 상태 명령어는 Slack 예약어 때문에 /agentstatus를 사용함.
• native commands를 쓰지 않더라도 channels.slack.slashCommand로 단일 slash command 흐름을 운영할 수 있음.
• arg menu 렌더링은 옵션 수에 따라 buttons, static select, external select로 자동 전환됨.

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

​

스레딩 및 세션 관리

• DM: 에이전트 메인 세션으로 통합 (session.dmScope=main 기준).
• 채널: 각 채널별로 고유 세션 키 할당 (agent:<agentId>:slack:channel:<channelId>).
• 스레드: 필요한 경우 스레드별 세션 접미사(:thread:<ts>)를 생성하여 맥락을 격리함.
• 이력 관리: 새 스레드 세션 시작 시 기존 스레드 메시지 20개를 자동으로 가져옴 (initialHistoryLimit).

​

답장 스레드 설정

​

미디어 처리 및 전달

• 수신 첨부 파일: 토큰 인증 과정을 거쳐 Slack 전용 URL에서 파일을 다운로드함. 최대 용량 제한은 mediaMaxMb (기본 20MB) 설정을 따름.
• 발신 메시지: 최대 4,000자 단위로 자동 청킹(Chunking)됨. chunkMode="newline" 설정 시 문단 단위 분할을 우선함.
• 대상 지정: user:<id> (DM), channel:<id> (채널) 형식을 권장함.

​

이벤트 및 인터랙션

• 메시지 수정/삭제 및 리액션 추가/제거 이벤트를 시스템 이벤트로 수신함.
• 입력 중 표시: 스레드 내 실시간 상태 업데이트를 위해 assistant:write 권한이 필요함.
• 대화형 컴포넌트: 블록 액션 및 모달 상호작용 결과를 구조화된 시스템 이벤트로 에이전트에게 전달함.

​

확인 및 상태 리액션 (Ack/Typing)

• 확인 리액션 (ackReaction): 메시지 수신 시 즉시 표시할 이모지 지정 (예: "eyes").
• 입력 중 리액션 (typingReaction): 답변 생성 중 임시로 표시할 이모지 지정 (예: "hourglass_flowing_sand"). 완료 후 자동 삭제됨.

​

액션 게이트와 이벤트 동작

• 메시지 수정/삭제/thread broadcast는 시스템 이벤트로 매핑됨.
• reaction add/remove, member join/leave, channel rename, pin add/remove도 시스템 이벤트로 들어옴.
• channel_id_changed는 configWrites가 켜져 있으면 채널 config key migration에 활용될 수 있음.
• block actions와 modal interactions는 구조화된 Slack interaction: ... 시스템 이벤트를 생성함.

​

Manifest 예시와 scope 체크

{
  "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",
        "im:read",
        "im:write",
        "mpim:history",
        "mpim:read",
        "mpim:write",
        "users:read",
        "app_mentions:read",
        "assistant:write",
        "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"
      ]
    }
  }
}

​

텍스트 스트리밍 (Text Streaming)

1. Slack 앱 설정에서 Agents and AI Apps 기능 활성화.
2. 앱에 assistant:write 권한 부여.
3. 스레드 답장 환경 보장.

• 첫 번째 조각 수신 시 스트림 시작 (chat.startStream).
• 후속 조각들을 기존 스트림에 덧붙임 (chat.appendStream).
• 답변 종료 시 스트림 확정 (chat.stopStream).
• 미디어나 비텍스트 데이터는 일반 전송 방식으로 폴백됨.

​

문제 해결 (Troubleshooting)

• 채널에서 답장이 오지 않음: groupPolicy, channels.slack.channels, requireMention, 채널별 users allowlist를 순서대로 확인함.
• DM이 무시됨: channels.slack.dm.enabled, channels.slack.dmPolicy, pairing approvals, allowlist 엔트리를 점검함.
• Socket Mode 미연결: bot/app token과 Slack 앱 설정의 Socket Mode 활성화 여부를 검증함.
• HTTP mode 무응답: signing secret, webhook path, Slack Request URL, 계정별 고유 webhookPath를 확인함.
• Native/slash command가 동작하지 않음: channels.slack.commands.native: true 또는 channels.slack.slashCommand.enabled: true 의도와 Slack 쪽 slash command 등록 상태를 확인함.

​

설정 레퍼런스

• Configuration reference - Slack
• Pairing
• Channel routing
• Troubleshooting
• Configuration
• Slash commands