FAQ 및 문제 해결
AI Agent용 안내: 이 페이지의 Markdown 버전은 https://ankole.agentbull.com/ko-KR/docs/faq/index.md, 전체 문서 색인은 https://ankole.agentbull.com/ko-KR/llms.txt에 있습니다.
이 문서는 제품 전반을 소개하거나 프로바이더별 초기 설정 절차를 처음부터 반복하지 않습니다. 먼저 아래 표로 어느 경계에서 문제가 발생했는지 좁힌 뒤 해당 Identity Provider 또는 채팅 플랫폼 탭을 펼쳐 확인하세요. 설치와 최초 구성의 기준 문서는 Quick start입니다.
실패한 경계 찾기
| 관찰된 현상 | 먼저 확인할 것 |
|---|---|
/setup 또는 Console이 열리지 않음 |
배포 상태, control-plane, function-runtime, PostgreSQL, DNS, HTTPS |
| Console 또는 Pod은 열리지만 로그인이 실패하거나 디렉터리가 불완전함 | 엔터프라이즈 IdP SSO, 패스워드리스 이메일 OTP(authn.email.mail 기반 SiteCredential), principals.pod_login_policy 및 siteadmin / pod_admin 멤버십 |
| Console 내부 대화는 동작하지만 특정 메신저의 메시지가 들어오지 않음 | 해당 Channel Provider 설정과 Signal Routing 규칙 |
| 메신저 메시지는 Ankole에 들어오지만 Agent가 답변을 생성하지 못함 | LLM Provider, 모델 프로필, Worker 상태 |
| 특정 플랫폼 하나만 실패함 | 아래에서 해당 프로바이더 탭을 선택해 점검(다른 플랫폼용 해결책을 섞어 적용하지 마세요) |
모든 플랫폼의 공통 문제
/setup 또는 Console이 열리지 않을 때 무엇을 확인해야 하나요?
- 증상
- 페이지가 타임아웃되거나 연결이 거부되고, 502가 반환되거나 빈 화면만 표시되어 프로바이더 초기 설정을 시작할 수 없습니다.
- 의미
- 컨트롤 플레인이 정상 기동되지 않았거나 DNS, 리버스 프록시, Ingress가 트래픽을 컨트롤 플레인으로 전달하지 못하는 상태입니다. 뒤이어 보이는 프로바이더 오류도 대부분 이 연결 문제에서 비롯됩니다.
- 해결 방법
- control-plane, function-runtime, PostgreSQL, 리버스 프록시 상태를 점검하고 로그에 찍힌 첫 번째 오류부터 해결하세요.
- 컨트롤 플레인에 직접 접속할 때는 열리는데 외부 주소로만 실패한다면 DNS, TLS 인증서, 프록시 전달 대상을 확인하세요.
- 데이터베이스나 영속 볼륨을 섣불리 삭제하지 마세요. 프로세스 기동에 실패했다고 해서 데이터가 손상된 것은 아닙니다.
첫 설정용 activation code는 어디에 있나요?
- 증상
- /setup 화면에서 활성화 코드를 요구하지만 기동 터미널을 이미 닫았거나 로그에서 코드를 찾지 못했습니다.
- 의미
- 컨트롤 플레인은 최초 초기 설정 때만 이 활성화 코드를 사용하며, 첫 번째 siteadmin 관리자가 로그인을 마치면 코드는 즉시 만료됩니다.
- 해결 방법
- 아직 초기 설정을 완료하지 않았다면 Quick start에서 배포 방식 탭을 선택하고 안내된 로그 조회 명령을 실행하세요.
- 로그에서 SETUP ACTIVATION CODE 문자열을 검색하세요. 브라우저 저장소나 데이터베이스 테이블에서 코드를 추측해 찾으려 하지 마세요.
- 사이트에 이미 siteadmin(또는 Pod의 pod_admin) 관리자가 등록되어 있다면 다시 활성화할 필요 없이 패스워드리스 이메일 OTP(authn.email.mail 기반 SiteCredential) 또는 구성된 엔터프라이즈 IdP SSO로 바로 로그인하세요.
선택한 adapter가 여전히 Provider 목록에 없는 이유는 무엇인가요?
- 증상
- 플러그인을 활성화해 저장했는데도 설정 화면이나 Identity Provider, Signal Routing 페이지의 선택 목록에 나타나지 않습니다.
- 의미
- 초기 설정(/setup) 단계에서는 컴파일된 모든 플러그인이 열려 있지만, 초기 설정이 끝나면 저장된 활성화 목록에 있는 플러그인만 표시됩니다. 초기 설정 완료 후 Console에서 바꾼 플러그인 설정은 다음 컨트롤 플레인 시작 시점부터 적용됩니다.
- 해결 방법
- 아직 /setup을 진행 중이라면 Plugins 단계로 돌아가 선택 사항을 저장한 뒤 관리자 로그인 화면을 다시 여세요. 이때는 재시작할 필요가 없습니다.
- 이미 초기 설정을 마친 상태라면 컨트롤 플레인 프로세스만 재시작하세요(데이터 삭제나 PostgreSQL 재시작은 불필요). 재시작 후 플러그인이 활성 상태인지 확인하고 Provider 페이지로 돌아가세요.
- 재시작 후 컨트롤 플레인이 올라오지 않는다면 로그에서 첫 번째 플러그인 초기화 오류를 찾아 수정하세요.
어떤 채팅 플랫폼도 응답을 받지 못합니다. 이것도 채널 문제인가요?
- 증상
- 채널 대화, 다이렉트 메시지, 다른 메신저 앱이 모두 응답하지 않으며 Console에서 직접 시도한 Agent 대화도 실패합니다.
- 의미
- Console 내부 대화까지 함께 실패한다면 특정 메신저의 이벤트 권한 문제가 아니라 모든 채널이 공유하는 하위 경로—즉 LLM Provider, Agent 모델 프로필, 또는 Worker—에 원인이 있을 가능성이 높습니다.
- 해결 방법
- LLM Provider가 활성화되어 있고 자격 증명과 모델 이름이 실제로 유효한지 확인하세요.
- 대상 Agent의 primary 프로필이 유효하고 사용할 프로필이 올바르게 해석되는지 확인하세요. Console → Workers에서 해당 Agent의 Worker에 실패 사유가 있는지도 확인하세요.
- 먼저 Console에서 실제 모델 대화가 정상 완료되는 것을 확인한 뒤 선택한 채팅 플랫폼 설정으로 돌아가세요.
스케줄이 제때 실행되지 않았습니다. 먼저 무엇을 확인해야 하나요?
- 증상
- 스케줄이 등록되어 있지만 예상한 시각에 시작되지 않았거나 다음 실행 예정 시각이 기대와 다릅니다.
- 의미
- 스케줄이 비활성화 상태이거나 스케줄 시간대 또는 cron 표현식이 의도와 다르게 설정되었을 수 있으며, 예정된 트리거 시각에 컨트롤 플레인이 중지되어 있었을 수도 있습니다.
- 해결 방법
- 스케줄 상세 화면을 열어 활성화 여부를 확인하고 화면에 표시된 다음 실행 예정 시각을 점검하세요.
- 스케줄 시간대와 cron 표현식을 함께 확인하세요. 표현식을 머릿속으로 어림잡지 말고 Console이 계산해 보여 주는 예정 시각을 기준으로 삼으세요.
- Run now를 눌러 즉시 실행해 보세요. 수동 실행이 성공하면 시간 설정을 바로잡고, 실패하면 실행 기록에서 오류를 확인하세요.
스케줄이 실행되었는데 채팅에 결과가 도착하지 않은 이유는 무엇인가요?
- 증상
- 실행 기록은 남아 있지만 대상 채팅방이나 대화에 Agent의 응답 메시지가 올라오지 않았습니다.
- 의미
- 스케줄 트리거 자체는 정상 동작했으며, 그 뒤를 잇는 전달 경로(대상 라우트, Channel Provider, Agent 모델 프로필, 또는 가용 Worker) 중 한 곳에서 막힌 상태입니다.
- 해결 방법
- 실행 기록을 열어 결과 상태를 확인하고 첫 번째 오류 메시지를 읽으세요.
- 대상 Agent와 연결된 대화방(또는 채팅 목적지) 및 Signal Routing 규칙이 올바른지 점검하세요.
- Agent 모델 프로필이 정상 동작하는지, 그리고 Console → Workers에서 해당 Agent의 Worker에 실패 사유가 없는지 확인하세요.
Identity Provider 문제 해결
Identity Provider(IdP)는 콘솔 로그인과 연락처·조직도 동기화를 담당합니다. 조직에서 사용하는 인증 소스를 선택해 확인하세요. Slack Socket Mode, Entra ID Graph 웹훅 구독, Google Workspace 전체 동기화는 동작 방식이 서로 다르므로 점검 항목도 각각 다릅니다.
인증 리다이렉트 중 Slack 로그인이 실패합니다
- 증상
- Ankole로 돌아오기도 전에 Slack 화면에서 redirect_uri 불일치 오류가 뜨거나 엉뚱한 페이지로 이동합니다.
- 의미
- Slack 앱에 등록한 Redirect URL이 /setup에 표시된 콜백 URL과 정확히 일치하지 않거나, 다른 Slack 앱의 Client ID를 Ankole에 입력한 경우입니다.
- 해결 방법
- /setup 화면에 표시된 전체 콜백 URL을 복사해 Slack 앱의 OAuth & Permissions → Redirect URLs에 그대로 등록하세요.
- 스킴(https), 호스트, 포트, 경로, Provider ID까지 글자 단위로 대조하세요.
- Slack 앱 설정을 저장한 뒤 Ankole에서 새 로그인 시도를 시작하세요. 이미 열려 있던 이전 인증 화면은 재사용하지 마세요.
Slack 로그인은 되지만 멤버나 사용자 그룹이 누락됩니다
- 증상
- 관리자가 Console에 로그인하는 데는 성공했지만 Principals나 권한 그룹이 비어 있거나 최근 추가된 구성원이 보이지 않습니다.
- 의미
- 인증용 Slack 앱에 users:read, users:read.email, usergroups:read 등의 스코프가 빠져 있거나, 스코프를 추가하기 전에 발급받은 예전 Bot User OAuth Token을 그대로 쓰고 있거나, 아직 전체 동기화를 실행하지 않은 상태입니다.
- 해결 방법
- Quick start에 안내된 디렉터리 스코프를 모두 추가하세요.
- 스코프를 변경한 뒤에는 반드시 앱을 워크스페이스에 다시 설치하고 새로 발급된 Bot User OAuth Token을 IdP 설정에 저장하세요.
- 실시간 동기화를 점검하기 전에 먼저 수동 전체 동기화가 정상 완료되는지부터 확인하세요.
Slack이 전체 디렉터리 동기화를 완료했지만 이후 변경이 오래된 상태로 남습니다
- 증상
- 최초 전체 동기화 데이터는 들어왔지만 그 뒤로 바뀐 구성원이나 사용자 그룹 정보가 곧바로 반영되지 않습니다.
- 의미
- 실시간 동기화는 Slack Socket Mode를 통해 동작합니다. App-Level Token이 비어 있거나 접두사가 잘못되었을 때, Socket Mode가 꺼져 있을 때, 또는 컨트롤 플레인에서 Slack으로 아웃바운드 연결을 열 수 없을 때 발생합니다.
- 해결 방법
- IdP 설정에서 Sync directory changes를 켜고 유효한 App-Level Token(xapp-)을 입력하세요.
- Slack 앱 설정에서 Socket Mode를 활성화하고 컨트롤 플레인의 아웃바운드 인터넷 통신을 허용하세요.
- App-Level Token을 재발급했다면 Ankole 측 값도 함께 갱신한 뒤 디렉터리 변경을 일으켜 반영 여부를 테스트하세요.
채팅 채널 문제 해결
채팅 채널은 외부 메신저 메시지를 수신하고 Agent의 응답을 전달합니다. 문제가 발생한 Signal Routing 규칙의 플랫폼을 선택하세요(로그인용 IdP에 어떤 플랫폼을 썼는지는 채팅 채널 선택에 영향을 주지 않습니다).
Slack routing 규칙이 token 접두사를 거부합니다
- 증상
- 채널 라우팅 규칙을 저장할 때 연결을 열기도 전에 invalid_token_prefix 오류가 반환됩니다.
- 의미
- Bot Token과 App Token 입력란을 서로 바꾸어 넣었거나 다른 종류의 Slack 토큰을 입력한 경우입니다.
- 해결 방법
- Bot Token은 OAuth & Permissions에서 복사한 xoxb- 시작 토큰이어야 합니다.
- App Token은 connections:write 스코프를 포함해 발급한 xapp- 시작 토큰이어야 합니다.
- 두 값을 바로잡고 다시 저장하세요. 자격 증명 형식 검증을 통과하기 전에는 이벤트 구독 쪽을 뒤질 필요가 없습니다.
Slack 다이렉트 메시지는 되지만 채널 멘션이 되지 않습니다
- 증상
- 1:1 다이렉트 메시지에는 봇이 잘 답하지만, 채널에서 명시적으로 @멘션한 메시지는 Ankole에 들어오지 않습니다.
- 의미
- 해당 채널에 봇이 초대되어 있지 않거나 Slack 앱에 app_mentions:read 스코프와 app_mention 이벤트 구독이 빠져 있기 때문입니다.
- 해결 방법
- 테스트 채널에 봇을 먼저 초대하세요.
- Event Subscriptions에 app_mention 이벤트를 추가하고 OAuth 스코프에 app_mentions:read를 부여하세요.
- 스코프를 추가한 뒤 앱을 워크스페이스에 다시 설치하고 Ankole 라우팅 규칙의 Bot Token도 새 값으로 갱신하세요.
Slack이 @mention은 전달하지만 일반 채널 메시지는 전달하지 않습니다
- 증상
- addressed_only 모드는 잘 동작하지만 observe_all이나 may_intervene으로 바꾸어도 명시적 멘션만 인식합니다.
- 의미
- 라우팅 규칙은 이미 Ankole에 도착한 메시지를 어떻게 처리할지 정할 뿐입니다. Slack 앱 자체에 해당 채널 유형의 message.* 이벤트 구독과 *:history 스코프가 없으면 Slack이 멘션 없는 일반 메시지를 아예 보내 주지 않습니다.
- 해결 방법
- 먼저 addressed_only 모드에서 기본 왕복 대화가 정상 동작하는지 확인하세요.
- Quick start 안내에 따라 대상 대화 유형(공개 채널, 비공개 채널 등)에 맞는 message 이벤트와 history 스코프를 추가하세요.
- 앱을 다시 설치하고 Bot Token을 갱신한 뒤 그룹 메시지 모드를 전환하세요.
실패 경계가 여전히 불명확한 경우
문제를 한 번 다시 재현하면서 정확한 발생 시각, Agent UID, 라우팅 규칙 이름, 프로바이더 종류, 화면에 표시된 전체 오류 메시지를 기록하세요. 그런 다음 해당 시각 전후의 control-plane 및 Worker 로그만 발췌해 이벤트 이름을 기준으로 최초 오류 지점을 추적합니다.
이슈를 공유하거나 제보할 때 Client Secret, Bot Token, App Token, 모델 API 키, 전체 환경 변수 덤프, 마스킹하지 않은 설정 파일을 절대 첨부하지 마세요. 통째로 묶은 로그 아카이브 대신 민감 정보를 제거한 관련 로그 발췌본과 정확한 재현 절차만 전달해 주세요.