클로드 코드 슬랙 연동 방법: 설치·권한·오류 해결 가이드

목차

• 1. 개요
• 2. 사전 요구사항 체크리스트
• 3. 단계별 연동 가이드
• 4. 개발자 설정
• 5. 필수 권한 설정
• 6. 인증 문제 해결
• 7. 통합 동작 검증 체크리스트
• 8. 진단 도구 및 고급 문제 해결
• 9. 보안·프라이버시·규정 준수
• 10. 모범사례 및 운영 팁
• 11. FAQ
• 12. 부록: 참고 링크

1. 개요

Claude Code를 Slack에 통합하면 채널 대화에서 직접 코드 생성·리팩터링·디버깅 요청을 처리할 수 있습니다. Slack에서 @Claude로 멘션하면 스레드 컨텍스트와 연결된 GitHub 리포지토리를 분석해 PR 링크나 코드 블록으로 결과를 반환합니다. 이 통합은 Anthropic이 제공하는 공식 Claude Slack 앱을 기반으로 하며, 일반적으로 Bot Token(xoxb-)을 사용해 인증합니다.

2. 사전 요구사항 체크리스트

연동 전에 다음 항목을 확인하세요.

계정·권한

• Slack 워크스페이스 관리자 권한: 앱 설치 및 승인 필요
• Claude 계정: claude.ai/code 접근 가능 여부 확인
• GitHub 계정: 대상 리포지토리에 대한 읽기/쓰기 권한 필요

네트워크·보안·환경

• Outbound HTTPS 허용: api.slack.com, claude.ai, code.claude.com 도메인
• 시크릿 관리 정책 준비: Signing Secret, Bot Token 등
• 개발·프로덕션 분리 권장, ngrok 등 로컬 터널링 도구 준비

3. 클로드 코드 슬랙 연동 단계별 가이드

3-1. Slack 앱 생성

https://api.slack.com/apps에서 Create New App → From scratch를 선택해 앱을 생성합니다. 앱 생성 후 Basic Information에서 App ID, Client ID, Client Secret, Signing Secret을 안전하게 복사해 보관하세요. 이 값들은 OAuth와 이벤트 서명 검증에 사용됩니다.

3-2. OAuth & 권한 설정(필수 스코프 및 Redirect URL)

OAuth & Permissions에서 Redirect URLs를 추가하고 Bot Token Scopes에 필요한 권한을 등록한 뒤 Install to Workspace를 진행하세요. 발급된 Bot Token(xoxb-)은 안전하게 보관해야 합니다.

https://slack.com/oauth/v2/authorize?client_id=YOUR_CLIENT_ID&scope=chat:write,channels:read,app_mentions:read&redirect_uri=https://your-service.example.com/oauth/callback

curl -X POST https://slack.com/api/oauth.v2.access \
  -d "client_id=YOUR_CLIENT_ID" \
  -d "client_secret=YOUR_CLIENT_SECRET" \
  -d "code=AUTHORIZATION_CODE" \
  -d "redirect_uri=https://your-service.example.com/oauth/callback"

3-3. Events API 및 Interactivity 설정(서명 검증)

Event Subscriptions에서 Enable Events를 켜고 Request URL을 등록하세요. Request URL 검증을 위해 서버는 url_verification challenge에 JSON으로 즉시 응답해야 합니다. 구독할 이벤트로는 app_mention, message.channels, message.im 등을 고려하세요.

서명 검증 절차는 Signing Secret으로 HMAC-SHA256을 계산해 X-Slack-Signature와 비교하는 방식입니다. 타임스탬프 차이는 5분 이내로 검증해야 합니다.

const crypto = require('crypto');

function verifySlackSignature(signingSecret, headers, rawBody) {
  const timestamp = headers['x-slack-request-timestamp'];
  const signature = headers['x-slack-signature'];
  
  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - timestamp) > 300) {
    throw new Error('Request timestamp expired');
  }
  
  const sigBasestring = `v0:${timestamp}:${rawBody}`;
  const hmac = crypto.createHmac('sha256', signingSecret);
  const calculatedSig = 'v0=' + hmac.update(sigBasestring).digest('hex');
  
  if (calculatedSig !== signature) {
    throw new Error('Invalid signature');
  }
  return true;
}

import hmac
import hashlib
import time

def verify_slack_signature(signing_secret, timestamp, signature, raw_body):
    if abs(time.time() - int(timestamp)) > 300:
        raise Exception("Request timestamp expired")
    
    sig_basestring = f"v0:{timestamp}:{raw_body}".encode()
    calculated_sig = 'v0=' + hmac.new(
        signing_secret.encode(),
        sig_basestring,
        hashlib.sha256
    ).hexdigest()
    
    if calculated_sig != signature:
        raise Exception("Invalid signature")
    return True

3-4. Claude Code 쪽 설정(워크스페이스 연결·권한 승인)

Slack 앱 마켓플레이스에서 Claude 앱을 설치한 뒤 Claude의 Integrations 또는 Settings → Slack에서 워크스페이스를 연결하세요. GitHub 연동을 통해 작업할 리포지토리를 선택하면 Claude Code가 명시적으로 승인된 리포지토리만 접근합니다.

3-5. 토큰·시크릿 저장 및 보안 권고

민감 정보는 절대 코드에 하드코딩하지 말고 환경변수나 시크릿 매니저(AWS Secrets Manager, GCP Secret Manager, Azure Key Vault 등)에 보관하세요. 노출 시에는 즉시 시크릿 재발급 및 토큰 폐기 절차를 수행해야 합니다.

export SLACK_BOT_TOKEN="xoxb-your-bot-token"
export SLACK_SIGNING_SECRET="your-signing-secret"
export SLACK_CLIENT_SECRET="your-client-secret"

aws secretsmanager get-secret-value \
  --secret-id slack/bot-token \
  --query SecretString \
  --output text

3-6. 채널에 앱 추가 및 초간단 테스트

채널에 봇을 초대한 뒤 아래 테스트 케이스를 수행해 연동 상태를 확인하세요. 예: @Claude Fix bug in function foo(), /claude-code generate function, 버튼 클릭 테스트 등.

4. 클로드 코드 슬랙 연동 개발자 설정

OAuth state 파라미터 처리를 통해 CSRF를 방지하고 Redirect URL을 환경(개발·스테이징·프로덕션)별로 등록하세요. 슬래시 커맨드와 모달 설계, 메시지 라우팅 조건을 명확히 정의해 Claude Code로 올바르게 라우팅되도록 합니다.

5. 클로드 코드 슬랙 연동 필수 권한 설정

최소 권한 원칙을 적용해 필요한 스코프만 부여하세요. 대표 스코프: chat:write, channels:read, app_mentions:read 등이며, 각 스코프의 보안 영향을 검토한 뒤 승인 절차를 마련하세요.

6. 클로드 코드 슬랙 연동 인증 문제 해결

자주 발생하는 오류와 해결책 템플릿을 정리합니다.

redirect_uri_mismatch

원인: Redirect URL 불일치(프로토콜·도메인·경로·쿼리까지 정확히 일치해야 함). 해결: Slack 앱의 Redirect URLs에 실제 사용 URL을 정확히 추가한 뒤 재시도하세요.

invalid_client

원인: 잘못된 client_id 또는 client_secret. 해결: Basic Information에서 자격증명을 재확인하고 필요 시 재발급하세요.

insufficient_scope

원인: 토큰에 필요한 스코프 누락. 해결: 필요한 스코프를 추가한 뒤 앱을 다시 설치(Reinstall)하세요.

token_revoked / token_expired

원인: 토큰 철회 또는 앱 제거. 해결: 워크스페이스 관리자에게 앱 재설치 요청, 새 토큰으로 시크릿 업데이트.

앱이 채널에 메시지 전송 실패(not_in_channel)

해결: 채널에서 /invite @your-bot로 봇 초대 또는 채널 설정에서 앱 추가, chat:write 권한 확인.

7. 통합 동작 검증 체크리스트

엔드투엔드 테스트로 주요 항목을 확인하세요: OAuth 설치, Events 구독 검증, 서명 검증, Slash command, Claude 라우팅, 민감정보 로그 마스킹 등.

8. 고급 문제 해결 및 진단 도구

Slack 앱 관리 콘솔의 Event delivery와 ngrok 대시보드, 서버 로그를 활용해 요청·응답을 분석하세요. Express.js와 같은 프레임워크에서는 서명 검증을 위해 raw body를 사용해야 합니다.

ngrok http 3000

app.use('/slack/events', express.raw({ type: 'application/json' }), (req, res) => {
  const rawBody = req.body.toString();
  verifySlackSignature(signingSecret, req.headers, rawBody);
  const payload = JSON.parse(rawBody);
  // 이후 처리
});

curl -X POST https://slack.com/api/chat.postMessage \
  -H "Authorization: Bearer xoxb-your-bot-token" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "C123456",
    "text": "Test message from Claude Code"
  }'

async function postMessageWithRetry(channel, text, retries = 3) {
  for (let i = 0; i < retries; i++) {
    const response = await fetch('https://slack.com/api/chat.postMessage', {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${process.env.SLACK_BOT_TOKEN}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ channel, text })
    });
    
    if (response.ok) return response.json();
    
    if (response.status === 429) {
      const retryAfter = parseInt(response.headers.get('Retry-After') || '1');
      await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
      continue;
    }
    
    throw new Error(`API error: ${response.status}`);
  }
}

9. 보안·프라이버시·규정 준수

최소 권한 원칙, 민감 데이터 자동 마스킹, 로그 보존 정책, 엔터프라이즈 요구사항(SAML/SCIM, 데이터 레지던시 등)을 준수하세요. 분기별 액세스 검토를 통해 불필요한 권한을 제거합니다.

10. 모범사례 및 운영 팁

Canary 배포로 일부 채널에서 먼저 테스트하고, 모니터링 지표와 알람을 설정해 문제 발생 시 빠르게 대응하세요. 시크릿 재발급 시 사전 공지와 테스트 환경 검증을 필수로 합니다.

11. 자주 묻는 질문 (FAQ)

Q. 앱을 초대했는데 메시지를 못받아요

A. 채널에 봇이 초대되었는지(/invite @your-bot), Bot Token Scopes에 chat:write가 포함되어 있는지, Event Subscriptions에서 app_mention을 구독했는지 확인하세요.

Q. OAuth 에러가 납니다

A. 오류 유형별로 원인·해결 방법이 다릅니다. redirect_uri_mismatch, invalid_client, insufficient_scope 등의 항목을 6장 인증 문제 해결 섹션에서 확인하세요.

Q. Claude가 특정 채널 메시지를 못 읽습니다

A. channels:history 권한과 봇 초대 상태, 워크스페이스 정책 차단 여부를 확인하세요.

Q. 서명 검증 실패가 계속 발생합니다

A. 요청 바디를 raw body로 사용했는지, 타임스탬프 차이가 5분 이내인지, Signing Secret이 최신 값인지 확인하세요. Express/Flask에서는 JSON 파싱 전에 raw body를 별도 저장해야 합니다.

Q. Claude Code 세션이 열리지 않습니다

A. claude.ai/code에서 GitHub 연동 상태, Slack 앱 Home의 라우팅 모드, 멘션에 포함된 키워드(예: code, fix, bug)를 확인하세요.

12. 부록: 참고 링크

• Claude Code Slack 공식 문서
• Claude and Slack 설명 페이지
• Claude 블로그: Claude Code and Slack
• Claude 지원 문서: Using Claude in Slack
• Slack OAuth 설치 문서
• Slack Events API
• Slack app_mention 이벤트 레퍼런스
• Slack 서명 검증 가이드
• Slack Rate Limits

이 글이 마음에 드세요?

RSS 피드를 구독하세요!