FAQ 및 문제 해결

이 페이지는 제품 개요가 아니며 각 provider 설정 가이드를 반복하지 않습니다. 가장 먼저 실패한 경계를 찾은 다음 관련 identity 또는 채팅 provider를 선택하세요. Quick start는 설치와 첫 설정에 있어 여전히 source of truth입니다.

실패한 경계 찾기

관찰된 현상	먼저 확인할 것
`/setup` 또는 Console이 열리지 않음	배포, control plane, DNS, HTTPS
Console은 열리지만 로그인이 실패하거나 디렉터리가 불완전함	Identity Provider (IdP)
Console에서는 Agent가 작동하지만 특정 IM이 메시지를 받지 못함	해당 Channel Provider와 signal routing 규칙
IM 메시지는 Ankole에 들어오지만 Agent가 답변을 생성하지 못함	LLM Provider, model profile, Worker
하나의 플랫폼만 실패	아래에서 해당 Provider를 선택하고 다른 플랫폼의 수정 방법을 적용하지 마세요

모든 플랫폼의 공통 문제

/setup 또는 Console이 열리지 않을 때 무엇을 확인해야 하나요?

증상

페이지가 타임아웃되거나, 연결을 거부하거나, 502를 반환하거나, 빈 화면으로 남습니다. Provider setup이 아직 시작되지 않았습니다.

의미

control plane이 정상이 아니거나, DNS, 리버스 프록시, Ingress가 control plane으로 트래픽을 보내지 않습니다. 이후의 Provider 오류는 대개 그 결과입니다.

해결 방법

control plane, PostgreSQL, 리버스 프록시를 확인하세요. 로그에서 첫 번째 오류를 수정하세요.
control plane에 직접 접근이 되면 DNS, TLS, 프록시 대상을 확인하세요.
데이터베이스나 영구 볼륨을 삭제하지 마세요. 시작 실패가 데이터 손상을 증명하지는 않습니다.

배포 확인하기 로그 읽기

첫 설정용 activation code는 어디에 있나요?

증상

/setup이 activation code를 요구하지만, 시작 터미널은 닫혀 있거나 로그에서 코드를 찾을 수 없습니다.

의미

control plane은 이 code를 첫 설정에만 사용합니다. 첫 번째 관리자가 로그인하면 만료됩니다.

해결 방법

설정이 완료되지 않았다면 Quick start에서 배포 방법을 선택하고 해당 탭의 로그 명령을 사용하세요.
SETUP ACTIVATION CODE를 검색하세요. 브라우저 저장소나 데이터베이스 행에서 코드를 추측하지 마세요.
인스턴스에 root 관리자가 이미 있다면 다시 활성화하지 말고 설정된 IdP로 로그인하세요.

activation code 읽기

선택한 adapter가 여전히 Provider 목록에 없는 이유는 무엇인가요?

증상

플러그인이 활성화로 저장되었지만, 해당 옵션이 setup이나 identity, signal-routing 페이지에 나타나지 않습니다.

의미

첫 설정은 컴파일된 모든 플러그인을 사용 가능하게 유지하고, 이후 구성을 현재 저장된 선택으로 필터링합니다. 설정 후 Console에서 저장한 플러그인 변경은 다음 control plane 시작 때 적용됩니다.

해결 방법

아직 /setup에 있다면 Plugins로 돌아가 선택을 저장하고 관리자 로그인을 다시 여세요. 재시작은 필요하지 않습니다.
설정이 완료되었다면 control plane만 재시작하세요. 데이터를 제거하거나 PostgreSQL을 재시작하지 마세요. 플러그인이 활성 상태인지 확인하고 Provider 페이지로 돌아가세요.
control plane이 시작되지 않으면 로그에서 첫 번째 플러그인 초기화 오류를 수정하세요.

Agent Library에서 Plugins 활성화

어떤 채팅 플랫폼도 응답을 받지 못합니다. 이것도 채널 문제인가요?

증상

채널, 다이렉트 메시지, 두 번째 채팅 앱이 모두 실패합니다. Console에서의 직접 Agent 대화도 실패합니다.

의미

Console 경로도 실패한다면 공유 다운스트림 경로가 원인일 가능성이 높습니다. LLM Provider, Agent model profile, 또는 Worker이며, 하나의 플랫폼 이벤트 권한이 아닙니다.

해결 방법

LLM Provider가 활성화되었는지, credential과 모델 이름이 작동하는지 확인하세요.
Agent에 primary, light, heavy profile이 있고 Worker가 하나 이상 준비되었는지 확인하세요.
Console에서 실제 모델 대화 하나를 완료한 다음 선택한 채팅 플랫폼 탭으로 돌아가세요.

LLM Provider와 Agent 구성 Worker fleet

스케줄이 제때 실행되지 않았습니다. 먼저 무엇을 확인해야 하나요?

증상

스케줄은 존재하지만 예상 시간에 시작되지 않았거나, 다음 실행이 기대와 일치하지 않습니다.

의미

스케줄이 비활성화되었거나, 인스턴스 시간대나 cron 표현식이 잘못되었거나, 트리거 시점에 control plane이 실행 중이 아니었을 수 있습니다.

해결 방법

스케줄을 열고 활성화되었는지 확인한 후 표시된 다음 실행 시각을 검토하세요.
인스턴스 시간대와 cron 표현식을 확인하세요. 표현식에서 추정하지 말고 Console이 표시하는 시각을 사용하세요.
Run now를 선택하세요. 작동하면 시간 설정을 수정하세요. 실패하면 실행 기록을 검토하세요.

스케줄 구성 및 조회

스케줄이 실행되었는데 채팅에 결과가 도착하지 않은 이유는 무엇인가요?

증상

실행 기록은 존재하지만 대상 채팅이나 대화에 Agent 메시지가 도착하지 않았습니다.

의미

트리거는 작동했습니다. 문제는 이후 경로에 있습니다. 대상 route, Channel Provider, Agent 모델, 또는 사용 가능한 Worker입니다.

해결 방법

실행 기록을 열고 결과를 확인한 후 첫 번째 오류를 읽으세요.
대상 Agent와 대화 또는 채팅 목적지, 그리고 signal routing 규칙을 확인하세요.
Agent model profile이 작동하는지, Worker가 하나 이상 준비되었는지 확인하세요.

스케줄 실행 기록 조회 signal routing 규칙 확인

Identity Provider 문제 해결

IdP는 로그인, 연락처, 조직 동기화를 소유합니다. 엔터프라이즈가 사용하는 identity 소스를 선택하세요. Slack Socket Mode, Entra ID Graph 구독, Google Workspace 전체 동기화는 서로 다른 메커니즘이며 다른 확인이 필요합니다.

인증 리다이렉트 중 Slack 로그인이 실패합니다

증상

Slack이 Ankole로 돌아오기 전에 redirect_uri 불일치를 보고하거나, 인증이 잘못된 페이지로 돌아갑니다.

의미

Slack Redirect URL이 /setup이 표시하는 콜백과 정확히 일치하지 않거나, Ankole에 다른 앱의 Client ID가 들어 있습니다.

해결 방법

/setup의 전체 콜백을 OAuth & Permissions → Redirect URLs에 복사하세요.
scheme, host, port, path, Provider ID를 문자 단위로 비교하세요.
Slack 앱을 저장하고 Ankole에서 새 로그인을 시작하세요. 이전 인증 페이지를 재사용하지 마세요.

Slack 로그인은 되지만 멤버나 사용자 그룹이 누락됩니다

증상

관리자가 Console에 들어왔지만 Principals나 권한 그룹이 비어 있거나 최근 멤버가 빠져 있습니다.

의미

identity 앱에 users:read, users:read.email, team:read가 없거나, Bot User OAuth Token이 새 스코프보다 이전 버전이거나, 전체 동기화가 실행되지 않았습니다.

해결 방법

Quick start에 나열된 identity 스코프를 추가하세요.
스코프 변경 후 앱을 워크스페이스에 다시 설치하고 새 Bot User OAuth Token을 IdP에 저장하세요.
realtime sync를 문제 해결하기 전에 전체 동기화를 검증하세요.

Slack이 전체 디렉터리 동기화를 완료했지만 이후 변경이 오래된 상태로 남습니다

증상

첫 동기화에는 데이터가 있지만 멤버나 사용자 그룹 변경이 신속히 나타나지 않습니다.

의미

Realtime sync는 Socket Mode를 사용합니다. App-Level Token이 없거나, 잘못된 접두사이거나, Socket Mode가 꺼져 있거나, control plane이 Slack에 도달할 수 없습니다.

해결 방법

IdP에서 Sync directory changes를 켜고 유효한 App-Level Token을 제공하세요.
Slack에서 Socket Mode를 활성화하고 control plane의 아웃바운드 인터넷 접근을 허용하세요.
App-Level Token 교체 후 Ankole의 값을 업데이트하고 새 디렉터리 변경으로 테스트하세요.

Quick start에서 Slack IdP 구성

채팅 채널 문제 해결

채팅 채널은 IM 메시지를 받고 Agent 답변을 보냅니다. routing 규칙에서 플랫폼을 선택하세요. IdP에 사용된 플랫폼은 이 선택을 바꾸지 않습니다.

Slack routing 규칙이 token 접두사를 거부합니다

증상

채널 저장 시 연결이 열리기 전에 invalid_token_prefix가 반환됩니다.

의미

Bot Token과 App Token이 뒤바뀌었거나, 한 값이 다른 Slack token 유형입니다.

해결 방법

Bot Token은 xoxb-로 시작해야 하며 OAuth & Permissions에서 가져와야 합니다.
App Token은 xapp-로 시작해야 하며 connections:write를 포함해야 합니다.
값을 수정하고 다시 저장하세요. credential 검증이 통과하기 전에 이벤트를 조사하지 마세요.

Slack 다이렉트 메시지는 되지만 채널 멘션이 되지 않습니다

증상

봇이 다이렉트 메시지에 답하지만, 채널의 명시적 @mention이 Ankole에 도달하지 않습니다.

의미

봇이 채널 멤버가 아니거나, 앱이 app_mentions:read와 함께 app_mention을 구독하지 않습니다.

해결 방법

테스트 채널에 봇을 초대하세요.
Event Subscriptions에 app_mention을 추가하고 app_mentions:read를 부여하세요.
스코프 변경 후 앱을 다시 설치하고 Ankole의 Bot Token을 업데이트하세요.

Slack이 @mention은 전달하지만 일반 채널 메시지는 전달하지 않습니다

증상

addressed_only는 작동하지만 observe_all이나 may_intervene도 명시적 멘션만 봅니다.

의미

routing 규칙은 Ankole이 받는 메시지를 제어합니다. Slack 앱에 여전히 해당 대화 유형에 맞는 message 이벤트나 history 스코프가 없습니다.

해결 방법

먼저 addressed_only 경로가 완전히 작동하는지 확인하세요.
Quick start에 나온 대로 대상 대화 유형의 message 이벤트와 history 스코프를 추가하세요.
앱을 다시 설치하고 token을 업데이트한 다음 그룹 메시지 모드를 변경하세요.

Quick start에서 Slack 채널 구성

실패 경계가 여전히 불명확한 경우

결함을 한 번 재현하세요. 정확한 시각, Agent UID, routing 규칙 이름, Provider, 인터페이스가 표시한 전체 오류를 기록하세요. 그런 다음 그 시각 주변의 control-plane 및 Worker 로그만 수집하고 이벤트 이름으로 첫 번째 오류를 찾으세요.

Client Secret, Bot Token, App Token, 모델 API key, 전체 환경 덤프, 또는 비식별화되지 않은 구성 파일을 보내지 마세요. 이슈를 보고할 때는 전체 로그 아카이브 대신 비식별화된 로그와 정확한 재현 단계를 포함하세요.

Ankole 로그 읽기