[Docs/Bug] 매니페스트대로 앱을 만들어도 channels:join, chat:write.public, team:read, mpim:read 누락 경고가 뜬다

[lidge-jun]

증상

jaw slack manifest 가 출력하는 매니페스트로 Slack 앱을 만들어 설치했는데, 서버 기동 후 스코프가 부족하다는 경고가 떴다.

[slack:scopes] Slack app grant is missing 4 scope(s) — features degrade without:
  channels:join, chat:write.public, team:read, mpim:read
  — add them under OAuth & Permissions, then reinstall the app to your workspace

/api/health 의 slackScopes.missingCapabilities 에도 같은 4개가 잡힌다.

헷갈렸던 지점

처음에는 같은 워크스페이스에 이미 붙어 있던 기존 cli-jaw 앱의 매니페스트를 복사해서 새 앱을 만들었다. 그쪽에도 이 4개가 없었다. 즉 기존에 잘 돌던 앱도 이 스코프가 빠진 채로 동작 중이었고, 새 앱을 만들 때 그걸 그대로 물려받았다.

그래서 아래 두 가지를 구분하기 어려웠다.

• 이 4개가 정말 필요한 것인지 (없어도 기존 앱은 돌고 있었음)
• 경고가 뜨는데 왜 소켓은 정상 연결되는지 (hello received, connected 는 나옴)

메시지에 features degrade without 이라고만 적혀 있어서, 무슨 기능이 어떻게 degrade 되는지 판단할 근거가 없었다. 결국 안전하게 4개를 추가해서 재설치했다(missingCapabilities: []). Bot Token 값은 재설치 후에도 바뀌지 않았다.

제안

• 스코프별로 무엇이 안 되는지 한 줄씩 붙여주면 좋겠다 (예: channels:join 없으면 auto-join 불가)
• required 와 optional 을 로그에서 명확히 갈라주면 좋겠다. 지금은 missingRequired: [] 인데도 경고 문구는 동일한 톤이라 심각도 판단이 안 된다
• 가능하면 jaw slack manifest 출력에 이 4개를 포함시켜서, 매니페스트대로 만들면 경고가 안 뜨게 해주면 좋겠다

환경

• cli-jaw 2.17.22
• node v24.19.0
• Slack Socket Mode

[parkjs101]

확인했습니다. 결론부터: 매니페스트는 손댈 게 없고, 로그 문구만 고칩니다. #482 (draft) 로 올렸습니다.

세 번째 제안(매니페스트에 4개 포함)은 이미 반영돼 있습니다

src/slack/manifest.ts 의 bot_token_scopes 기준입니다.

스코프	배포
team:read, mpim:read	v2.14.0 (2026-08-11)
channels:join, chat:write.public	v2.17.10 (2026-08-21)

2.17.22 에서 jaw slack manifest 를 그대로 쓰셨다면 4개가 모두 출력됩니다. 본문에 적어주신 대로 기존 앱의 매니페스트를 복사하신 게 원인인데, 더 정확히는 그 기존 앱이 v2.17.10 이전에 설치된 것으로 보입니다. Slack 은 설치 시점에 grant 를 고정하고 cli-jaw 를 업그레이드해도 따라오지 않아서, 구버전으로 설치된 앱은 재설치 전까지 계속 이 경고를 냅니다. "기존에 잘 돌던 앱도 이 스코프가 빠진 채 동작 중" 이라고 관찰하신 게 그 상태입니다. 재설치가 유일한 해소 경로라 이번 조치는 맞았습니다.

앞의 두 제안은 유효합니다 — 그게 이번 수정입니다

판정 데이터는 처음부터 missingRequired / missingCapabilities 로 나뉘어 있었습니다. 납작해진 건 보고 단계뿐이었고, 두 배열을 이어붙인 뒤 severity 를 전체에 하나만 골랐습니다. 그래서 missingRequired: [] 인데도 missing 4 scope(s) 가 WARN 으로 나갔고, 반대로 required 가 하나라도 빠지면 optional 까지 the transport needs 로 승격됐습니다. 심각도를 읽을 수 없던 게 맞습니다.

severity 당 한 줄씩, 각자 자기 로그 레벨로 바꿨습니다.

[WARN] [slack:scopes] the transport needs 1 scope(s): chat:write — reinstall: ...
[INFO] [slack:scopes] 4 optional scope(s) not granted: channels:join, chat:write.public,
       team:read, mpim:read — messaging is unaffected; reinstall: ...

optional 만 빠진 경우는 이제 WARN 이 아니라 INFO 이고, messaging is unaffected 를 명시합니다 — "경고가 뜨는데 왜 소켓은 정상 연결되는지" 가 실제 질문이었으니 거기에 답하는 게 맞다고 봤습니다.

바뀌는 건 로그 문구와 레벨뿐입니다. 스코프 분류 기준, /api/health 의 slackScopes 응답, 상태 필드는 그대로입니다.

스코프별 영향 설명(channels:join 없으면 auto-join 불가 등)은 이번엔 넣지 않았습니다. 지금 코드 주석에만 있는 설명이라 데이터 구조를 바꿔야 하고, 심각도 구분만으로 판단 근거는 충분해 보여서 별건으로 두겠습니다. 필요하시면 후속으로 열겠습니다.

좋은 리포트 감사합니다. 특히 "기존 앱도 빠진 채 돌고 있었다" 는 관찰이 원인 특정에 결정적이었습니다.