본문으로 건너뛰기

Slack 봇 앱 만들기, 클릭 대신 Manifest 자동화로 정리한 이야기

Giacomo

2026.05.18

Slack 봇 앱 만들기, 클릭 대신 Manifest 자동화로 정리한 이야기

한 줄 요약

Slack 봇 앱을 만들 때마다 반복되던 manifest 작성 → 검증 → 앱 생성 → 프로젝트 연결 → 워크스페이스 설치 → 결과 확인 흐름을, Slack CLI와 Slack Web API를 조합해서 재현 가능한 자동화 절차로 정리했습니다.

이런 분들께 도움이 됩니다

Slack 봇을 여러 개 만들어야 하는 분

Hermes/OpenClaw/Claude Code 같은 에이전트 봇을 Slack 워크스페이스에 연결하려는 분

Slack App Manifest, Socket Mode, bot token/app token 구분이 매번 헷갈리는 분

자기 워크스페이스 요금제와 권한 범위에 맞춰 manifest scope를 안전하게 고르고 싶은 분

“Slack 앱 생성도 CLI로 끝까지 자동화할 수 있나?”를 확인하고 싶은 분

---

시작점: Slack 봇 만들기는 은근히 반복 작업이 많았습니다

Slack 봇을 하나 만들 때는 웹 콘솔에서 클릭 몇 번으로 끝나는 것처럼 보입니다. 그런데 에이전트 봇을 여러 개 만들거나, 런타임별로 Slack 앱을 분리하려고 하면 이야기가 달라집니다.

반복되는 작업이 꽤 많았습니다.

앱 이름과 봇 표시 이름 정하기

Bot scope 고르기

Event Subscription 설정하기

Socket Mode 켜기

App 생성 후 워크스페이스에 설치하기

생성된 App ID와 bot user가 맞는지 확인하기

runtime token과 CLI auth token을 섞지 않기

공유용 문서에서는 credential을 전부 가리기

처음에는 “Slack CLI면 manifest 파일로 앱 생성까지 한 번에 되지 않을까?”라고 생각했습니다.

그런데 실제 Slack CLI v4.0.1 기준으로 help를 확인해보니, slack manifest create처럼 manifest에서 앱 자체를 직접 생성하는 CLI subcommand는 보이지 않았습니다.

그래서 결론은 이렇게 바뀌었습니다.

> 앱 생성은 Slack Web API의 apps.manifest.create로 하고, Slack CLI는 프로젝트 생성/init, app link/install, manifest validate/info에 쓰자.

이렇게 나누니 흐름이 훨씬 명확해졌습니다.

---

만든 것 / 결과물

최종적으로는 Slack 봇 앱 생성 과정을 한 번에 따라갈 수 있는 자동화 가이드를 만들었습니다.

핵심 흐름은 아래 9단계로 정리했습니다.

Slack CLI 설치/인증 확인

워크스페이스 요금제/정책/봇 사용 범위 정리

manifest.json 생성

manifest 검증

apps.manifest.create API로 Slack app 생성

Slack CLI project 생성 또는 기존 project init

생성된 App ID를 project에 link

slack app install로 워크스페이스 설치

remote manifest / install status / bot user 확인

단순히 명령어를 모은 것이 아니라, 실제 자동화에서 막히기 쉬운 지점도 같이 적어두었습니다.

Slack CLI auth와 runtime bot token은 별개입니다.

apps.manifest.*에는 일반 xoxb-... bot token이 아니라 app configuration access token이 필요합니다.

Slack CLI v4.0.1에서는 slack app install --app <APP_ID>와 --environment deployed를 같이 쓰면 mismatched_flags가 날 수 있습니다.

template project를 복사할 때 symlink가 깨지면 runtime_not_found, ERR_MODULE_NOT_FOUND가 날 수 있습니다.

create response에는 credential 계열 값이 들어갈 수 있으므로, 공유용 report는 반드시 redaction이 필요합니다.

---

사용한 도구

Slack CLI v4.0.1: 프로젝트 생성, 인증 확인, app link/install, remote manifest 확인

Slack Web API apps.manifest.validate: manifest 사전 검증

Slack Web API apps.manifest.create: manifest 기반 Slack app 생성

jq: manifest JSON 압축, API payload 생성, response 검증

curl: Slack Web API 호출

Bash skeleton: 반복 생성 과정을 한 번에 묶는 자동화 틀

---

진행 과정

1. 먼저 Slack CLI가 어디에 설치되어 있는지 확인했습니다

Slack CLI 자동화에서 첫 번째로 확인한 것은 “내가 실행하는 slack이 진짜 Slack Developer CLI가 맞는가?”였습니다.

특히 WSL/Windows 환경에서는 slack 명령이 Windows Slack Desktop 앱 shim으로 잡힐 수 있습니다. 그래서 설치 경로와 버전을 먼저 확인하는 단계가 필요했습니다.

```bash

command -v slack

readlink -f "$(command -v slack)" || true

slack version

slack doctor

```

여기서 확인 기준은 단순합니다.

slack version이 정상 출력되는가?

slack doctor가 치명적인 문제 없이 끝나는가?

WSL이라면 /usr/local/bin/slack -> ~/.slack/bin/slack처럼 CLI 경로가 정상인가?

이 단계가 없으면 뒤에서 manifest나 install 문제가 아니라, 애초에 잘못된 CLI를 실행하고 있는 상황을 디버깅하게 됩니다.

2. manifest를 “봇 앱의 설계도”로 먼저 고정했습니다

다음은 manifest.json을 만들었습니다. 이번 기준은 Socket Mode 봇이었습니다.

Socket Mode를 쓰면 외부 Request URL을 열지 않아도 Slack 이벤트를 받을 수 있어서, 로컬 에이전트나 Hermes/OpenClaw류 봇에 특히 편합니다.

manifest에는 아래 요소를 넣었습니다.

앱 이름과 설명

bot user 표시 이름

App Home 메시지 탭 설정

bot OAuth scopes

Event Subscriptions

Socket Mode 활성화

token rotation 비활성화 여부

중요한 점은 scope를 처음부터 과하게 넣지 않는 것입니다. 공개 채널만 필요하면 channels:* 중심으로 시작하고, DM이나 비공개 채널이 필요할 때 im:*, groups:*, mpim:*를 추가하는 식이 더 안전합니다.

여기에 하나 더 추가한 기준이 있습니다. manifest를 만들기 전에, 봇에게 내 Slack 워크스페이스 요금제와 운영 범위를 먼저 말해주는 것입니다.

Slack App scope는 단순히 “봇이 뭘 하고 싶은가”만으로 정하면 과해지기 쉽습니다. 실제로는 아래 정보가 같이 들어가야 합니다.

워크스페이스 요금제: Free / Pro / Business+ / Enterprise Grid / 모름

봇이 들어갈 공간: 공개 채널만 / DM 포함 / 비공개 채널 포함 / 여러 워크스페이스 포함

설치 권한: 내가 직접 설치 가능 / 관리자 승인 필요 / 앱 승인 정책 있음

필요한 기능: 읽기, 쓰기, 멘션 응답, 홈 탭, 파일 업로드, slash command, workflow 연동 등

보안 기준: 최소 권한 우선 / 나중에 필요한 scope만 추가

그래서 manifest 초안을 만들 때는 이런 식으로 먼저 물어보게 했습니다.

```text

내 Slack 워크스페이스 요금제는 [요금제]이고,

봇은 [공개 채널/DM/비공개 채널]에서 [할 일]만 하면 됩니다.

이 조건에 맞춰 Slack App manifest의 OAuth scope를 최소 권한으로 골라주세요.

요금제나 관리자 정책 때문에 안 될 수 있는 기능은 [확인 필요]로 따로 표시해주세요.

```

이 한 줄이 꽤 중요했습니다.

봇이 무조건 많은 scope를 넣는 대신, “현재 요금제와 운영 범위에서 필요한 최소 scope”를 먼저 제안하게 만들 수 있었기 때문입니다.

3. “CLI만으로 다 될 것”이라는 가정을 버렸습니다

처음의 기대는 이랬습니다.

```text

manifest.json 준비 → slack manifest create → app 생성 완료

```

그런데 Slack CLI v4.0.1 기준으로 확인했을 때, 앱을 manifest에서 직접 생성하는 CLI subcommand가 없었습니다.

그래서 역할을 분리했습니다.

Slack Web API:

apps.manifest.validate

apps.manifest.create

Slack CLI:

auth login/list

project create/init

manifest validate/info

app link

app install

이 분리가 이번 작업의 핵심이었습니다.

“한 도구로 모든 것을 끝내기”가 아니라, 도구가 잘하는 영역을 나누니 자동화가 더 안정적이 됐습니다.

4. 앱 생성은 apps.manifest.create로 처리했습니다

manifest를 JSON string으로 압축한 뒤 Slack Web API로 보냈습니다.

```bash

MANIFEST_STRING="$(jq -c . manifest.json)"

curl -sS https://slack.com/api/apps.manifest.create \

-H "Authorization: Bearer ${SLACK_APP_CONFIG_TOKEN}" \

-H 'Content-Type: application/json; charset=utf-8' \

--data "$(jq -n \

--arg manifest "$MANIFEST_STRING" \

--arg team_id "$TEAM_ID" \

'{manifest: $manifest, team_id: $team_id}')" \

> create-response.raw.json

```

여기서 중요한 보안 기준도 같이 정했습니다.

원본 response는 로컬 secret 취급

공유용 파일은 credential 필드를 삭제한 redacted copy만 사용

token, ticket, challenge, app secret, signing secret은 채팅이나 공개 문서에 직접 노출하지 않기

팀 공유 문서나 공개 글에서는 아래처럼 표현하는 편이 안전합니다.

```text

SLACK_APP_CONFIG_TOKEN=[REDACTED]

APP_ID=A0123456789

TEAM_ID=T0123456789

```

5. 생성한 app을 Slack CLI project에 link했습니다

앱이 생성되면 App ID가 나옵니다. 이 App ID를 Slack CLI project에 연결했습니다.

```bash

slack app link \

--app "$APP_ID" \

--team "$TEAM_ID" \

--environment deployed \

--force \

--skip-update \

--no-color

```

자동화에서는 --force를 쓰기 전에 반드시 manifest validate가 통과되어야 한다고 기준을 잡았습니다.

그래야 잘못된 manifest를 강제로 덮어씌우는 일을 줄일 수 있습니다.

6. 설치 단계에서 실제 CLI 버전별 함정을 만났습니다

설치 명령은 아래처럼 정리했습니다.

```bash

slack app install \

--app "$APP_ID" \

--team "$TEAM_ID" \

--force \

--skip-update \

--no-color

```

여기서 확인한 pitfall이 있었습니다.

Slack CLI v4.0.1에서는 slack app install --app <APP_ID>와 --environment deployed를 함께 쓰면 mismatched_flags가 날 수 있습니다.

그래서 App ID로 설치할 때는 --environment를 생략하는 방식으로 정리했습니다.

이런 작은 버전별 함정은 문서에 꼭 남겨야 합니다. 다음에 같은 자동화를 다시 만들 때 가장 시간을 많이 잡아먹는 부분이기 때문입니다.

7. 설치 후에는 remote manifest와 bot user를 확인했습니다

앱 생성만 하고 설치하지 않으면 app은 Uninstalled 상태일 수 있습니다. 이 경우 bot user가 아직 보이지 않을 수 있습니다.

그래서 완료 기준을 “API 호출이 성공했다”가 아니라, 아래까지 확인하는 것으로 잡았습니다.

remote manifest에서 앱 이름 확인

bot user display name 확인

scope 확인

Socket Mode 설정 확인

Event Subscription 확인

users.list 또는 admin inventory에서 bot user 확인

예시는 아래와 같습니다.

```bash

slack manifest info \

--source remote \

--app "$APP_ID" \

--team "$TEAM_ID" \

--skip-update \

--no-color \

> remote-manifest.json

```

---

Before vs After

Before

Slack App 관리 화면에서 설정을 하나씩 클릭해야 했습니다.

어떤 scope를 넣었는지, Socket Mode를 켰는지 매번 다시 확인해야 했습니다.

앱 생성과 설치, project link의 경계가 흐릿했습니다.

Slack CLI token, bot token, app-level token이 섞여서 헷갈렸습니다.

비슷한 봇을 여러 개 만들 때 같은 실수를 반복할 가능성이 컸습니다.

After

manifest.json이 봇 설정의 기준 문서가 됐습니다.

앱 생성은 apps.manifest.create, 프로젝트 연결/설치는 Slack CLI로 역할을 나눴습니다.

실패 지점별 quick reference를 만들어 다음 디버깅 시간이 줄어들었습니다.

credential redaction 기준을 넣어 공유 가능한 문서와 로컬 secret을 분리했습니다.

여러 봇을 만들 때도 같은 skeleton을 재사용할 수 있게 됐습니다.

---

실제로 재사용할 수 있는 자동화 뼈대

전체 자동화는 이런 구조로 묶을 수 있습니다.

```text

환경변수 확인

→ manifest 생성

→ jq로 JSON 검증

→ apps.manifest.validate

→ apps.manifest.create

→ create response에서 APP_ID 추출

→ Slack CLI project 생성/init

→ app link

→ app install

→ remote manifest 저장

→ install summary 출력

```

자동화 스크립트에서 특히 신경 쓴 부분은 세 가지였습니다.

실패하면 바로 멈추게 set -euo pipefail 사용

jq -e '.ok == true'로 Slack API 응답을 기계적으로 검증

raw response와 redacted response를 분리

이렇게 해두면 “명령어는 성공한 것 같은데 실제로 앱이 설치됐나?” 같은 애매한 상태를 줄일 수 있습니다.

---

막힌 점과 해결

문제 1. Slack CLI만으로 manifest 앱 생성까지 가능한 줄 알았습니다

원인: CLI의 manifest 관련 명령이 앱 생성까지 포함한다고 가정했습니다.

해결: Slack CLI와 Slack Web API 역할을 분리했습니다.

배운 점: 자동화 전에 help와 실제 command surface를 확인해야 합니다.

문제 2. token 종류가 헷갈리기 쉬웠습니다

원인: Slack에는 CLI auth, app configuration token, bot token, app-level token이 모두 따로 존재합니다.

해결: 문서에서 token별 역할을 분리했습니다.

```text

Slack CLI auth token: 개발자 CLI 인증

SLACK_APP_CONFIG_TOKEN: apps.manifest.* 호출용

SLACK_BOT_TOKEN: 봇 런타임의 Web API 호출용

SLACK_APP_TOKEN: Socket Mode 연결용 app-level token

```

문제 2-1. 요금제와 워크스페이스 정책을 말하지 않으면 scope가 과해졌습니다

원인: 봇에게 “Slack 봇 만들어줘”라고만 말하면, 모델이 안전한 최소 권한보다 넓은 scope 조합을 제안할 수 있습니다.

해결: manifest 작성 전에 요금제, 설치 권한, 사용 채널, 필요한 기능을 먼저 입력값으로 고정했습니다.

기준: 현재 요금제나 관리자 정책에서 불확실한 기능은 바로 넣지 않고 [확인 필요]로 분리했습니다.

이렇게 하니 manifest가 “모든 기능을 넣은 만능 봇”이 아니라, 실제 워크스페이스에서 설치 가능한 운영 단위에 더 가까워졌습니다.

문제 3. slack app install 플래그 조합이 버전별로 민감했습니다

원인: --app <APP_ID>와 --environment deployed를 같이 썼을 때 mismatched_flags 발생 가능성이 있었습니다.

해결: App ID로 설치할 때는 --environment를 생략하는 기준을 남겼습니다.

문제 4. template 복사 시 symlink가 깨질 수 있었습니다

원인: node_modules/.bin 내부 symlink가 깨지면 Slack CLI hook 실행 중 runtime error가 발생할 수 있습니다.

해결: project template 복사 시 cp -a 또는 shutil.copytree(..., symlinks=True)를 사용하도록 정리했습니다.

---

결과와 배운 점

이번 작업에서 가장 큰 수확은 “Slack 봇 생성 자동화는 한 줄짜리 CLI 문제가 아니라, 권한·manifest·설치·검증을 분리하는 운영 문제”라는 점이었습니다.

정리하고 나니 다음과 같은 장점이 생겼습니다.

새 봇 앱을 만들 때 필요한 단계를 빠뜨리지 않습니다.

앱 생성과 설치 상태를 구분해서 볼 수 있습니다.

credential을 공유 문서에 실수로 노출할 위험이 줄어듭니다.

요금제와 워크스페이스 정책에 맞춰 scope를 고르니 불필요한 권한 요청이 줄어듭니다.

같은 방식으로 여러 에이전트 봇을 만들 때 재현성이 생깁니다.

실패했을 때 invalid_manifest, not_allowed_token_type, mismatched_flags 같은 에러를 더 빨리 좁힐 수 있습니다.

특히 에이전트 봇을 여러 런타임에 붙이는 경우에는 “대충 같은 Slack 앱을 공유”하는 것보다, app/token ownership을 명확히 나누는 편이 장기적으로 안전합니다.

---

다음에 해볼 것

manifest 템플릿을 봇 유형별로 나누기

공개 채널 전용 봇

DM 포함 봇

Socket Mode 봇

slash command 포함 봇

요금제/워크스페이스 정책별 scope 프리셋 만들기

Free/Pro에서 시작하는 최소 권한 프리셋

Business+/Enterprise Grid에서 관리자 승인이나 조직 정책을 따로 확인하는 프리셋

redaction 스크립트를 별도 유틸로 만들기

설치 후 bot user 확인까지 자동화 리포트에 넣기

Slack CLI 버전이 바뀔 때 slack app install 플래그 조합을 다시 검증하기

여러 봇을 만들 때 App ID, Team ID, token ownership을 inventory로 관리하기

---

봇용 지시문 세트

아래는 같은 작업을 AI 에이전트에게 맡길 때 사용할 수 있는 지시문입니다.

1. Slack 봇 앱 생성 자동화 계획 세우기

```text

Slack CLI와 Slack Web API를 사용해서 Slack 봇 앱 생성 자동화 절차를 설계해주세요.

조건:

- manifest.json 기반으로 앱을 만듭니다.

- Socket Mode 봇을 기본값으로 합니다.

- Slack CLI v4.0.1 기준으로 가능한 명령과 불가능한 명령을 구분합니다.

- apps.manifest.validate / apps.manifest.create API를 포함합니다.

- Slack CLI는 auth 확인, project create/init, app link, app install, manifest info에 사용합니다.

- token 종류를 CLI auth / app configuration token / bot token / app token으로 분리해서 설명합니다.

- raw credential은 절대 출력하지 않습니다.

- 마지막에 완료 기준 체크리스트를 만들어주세요.

```

2. manifest 초안 만들기

```text

다음 조건으로 Slack App manifest.json 초안을 만들어주세요.

앱 이름: [APP_NAME]

봇 표시 이름: [BOT_NAME]

동작 방식: Socket Mode

워크스페이스 요금제: [Free / Pro / Business+ / Enterprise Grid / 모름]

설치/승인 조건: [내가 직접 설치 가능 / 관리자 승인 필요 / 앱 승인 정책 있음 / 모름]

봇이 활동할 공간: [공개 채널만 / DM 포함 / 비공개 채널 포함 / 여러 워크스페이스 포함]

필요 기능:

- app mention 수신

- 공개 채널 메시지 수신

- 필요하면 DM 메시지 수신 옵션은 별도 주석으로 안내

- chat:write 가능

주의:

- 요금제와 워크스페이스 정책에 맞춰 scope를 최소 권한 기준으로 시작해주세요.

- 현재 요금제/정책에서 안 될 수 있거나 관리자 승인이 필요할 수 있는 기능은 [확인 필요]로 분리해주세요.

- token이나 secret 예시는 전부 [REDACTED]로 써주세요.

- JSON은 실제로 parse 가능한 형태여야 합니다.

```

3. 자동화 bash skeleton 만들기

```text

manifest 생성부터 Slack app 생성, project link, app install, remote manifest 확인까지 수행하는 bash skeleton을 작성해주세요.

필수 조건:

- set -euo pipefail 사용

- TEAM_ID, SLACK_APP_CONFIG_TOKEN, APP_NAME은 환경변수로 받기

- WORKSPACE_PLAN, BOT_SURFACE, INSTALL_POLICY 같은 입력값을 받아 manifest scope 선택 기준에 반영하기

- jq로 manifest JSON parse 검증

- apps.manifest.validate 응답에서 .ok == true 검증

- apps.manifest.create 응답에서 .ok == true와 app_id 존재 검증

- create-response.raw.json은 로컬 secret 취급

- 공유용 create-response.redacted.json 생성

- slack app install에서 --app APP_ID를 직접 쓸 때 --environment는 넣지 않기

- 마지막에 install-summary.txt 생성

```

4. 실패 로그 분석시키기

```text

아래 Slack CLI / Slack Web API 실패 로그를 보고 root cause를 좁혀주세요.

로그:

[여기에 secret 제거한 로그 붙이기]

분석 기준:

- invalid_manifest면 errors[].pointer 기준으로 수정 위치 제안

- not_allowed_token_type / invalid_auth면 token 종류 확인

- mismatched_flags면 Slack CLI 플래그 조합 확인

- runtime_not_found / ERR_MODULE_NOT_FOUND면 template 복사와 symlink 문제 확인

- 답변에는 secret을 재출력하지 말고 [REDACTED]로 처리해주세요.

```

---

공유 전 체크리스트

[ ] 문서에 실제 token, signing secret, app token, ticket/challenge가 없는가?

[ ] App ID / Team ID 공개 범위가 괜찮은가?

[ ] raw create response를 그대로 붙이지 않았는가?

[ ] 요금제/워크스페이스 정책/설치 승인 조건을 봇에게 먼저 알려 scope를 골랐는가?

[ ] manifest scope가 과하지 않은가?

[ ] apps.manifest.* 호출 token과 SLACK_BOT_TOKEN을 구분했는가?

[ ] 설치 후 remote manifest 확인 절차가 있는가?

[ ] Slack CLI 버전 기준을 적었는가?

[ ] 실패 대응 quick reference가 있는가?

---

짧은 마무리

이번 작업의 핵심은 “Slack 봇 만들기를 자동화했다”보다, 봇 앱 생성에 필요한 권한·설정·설치·검증의 경계를 분리했다는 점입니다.

Slack 앱은 한 번 만들고 끝나는 것처럼 보여도, 에이전트 봇이 늘어나면 반복 운영 작업이 됩니다. 이때 manifest와 검증 스크립트를 기준으로 삼으면, 클릭 작업을 줄이는 것뿐 아니라 실수와 보안 사고 가능성도 같이 줄일 수 있습니다.

2

함께 이야기해요 2

로그인하고 댓글을 남겨 주세요

김도경 프로필 이미지
김도경2026.09.28

잘 보고 갑니다.

어른아이J 프로필 이미지
어른아이J2026.05.18

좋은 사례 공유해주셔서 감사합니다

필요한 AI 정보만
메일함에 쏙쏙 넣어드려요.

지금 핫한 AI 소식부터 직접 해 본 사례까지, 월요일마다 무료로 받아보세요

이런 사례도 있어요

사례 전체 보기