A.3. 문제 해결
개요
CogentAI AAS(이하 AAS)를 쓰다가 만나는 증상을 영역별로 모았습니다. 각 표는 증상, 원인, 조치 순서로 되어 있습니다. 증상은 화면에 나오는 문구나 겪는 모습으로 적었습니다. 따옴표 「」 안의 글은 화면에 나오는 문구입니다.
아래 조치로 해결되지 않거나 조치가 「관리자에게 요청」이면, 다음을 담아 관리자에게 보냅니다. 화면 문구는 복사하거나 화면을 찍어 붙입니다.
- 어느 화면에서 무엇을 하다가 생겼는지
- 화면에 나온 문구
- 프로파일(작업공간 안의 AI 에이전트 한 명의 설정 묶음) 이름과 생긴 시각. 작업공간은 사용자마다 하나씩 만들어지는 AI 에이전트의 일터입니다.
게이트웨이(AI 에이전트가 메신저와 예약 작업을 받는 통로)를 켜고 끄는 일, 열린 문제를 닫는 일, 서버 설정을 바꾸는 일은 관리자가 합니다. 용어는 A.1. 용어 사전에 있습니다.
접속과 연결
| 증상 | 원인 | 조치 |
|---|---|---|
| 화면이 영어로 나옴 | 언어 설정이 「English」입니다. 다른 브라우저에서는 설정을 다시 정해야 합니다. | 「설정 › 내 화면」의 「언어」에서 「한국어」를 고릅니다. 메뉴가 영어라 찾기 어려우면 화면 위 막대의 번역 모양 아이콘에서 「한국어」를 고릅니다. 자세한 내용은 7.3. 내 화면 설정을 봅니다. |
| 화면의 날짜와 시각이 내 시간과 다름 | 「날짜 표시용 시간대」가 내 지역과 다르게 정해져 있습니다. | 「설정 › 내 화면」의 「날짜 표시용 시간대」를 「브라우저 시간대 따르기」나 내 지역으로 바꿉니다. 맞춘 뒤에도 어긋나는 시각이 있으면 어느 화면인지 관리자에게 알립니다. |
| 로그인했는데 「○○ 그룹에 속한 계정만 쓸 수 있습니다. 관리자에게 그룹 추가를 요청하세요.」가 나옴 | 내 계정에 AAS 를 쓸 자격이 없습니다. | 관리자에게 요청합니다. 예: 「제 계정(이메일 주소)에 AAS 사용 권한을 주세요.」 |
| 「로그인이 끝나 실시간 갱신을 멈췄습니다. 다시 로그인하세요.」 | 로그인 시간이 지나 세션이 끝났습니다. | 로그인 화면에서 다시 로그인합니다. |
| 「서버와의 연결이 끊겨 다시 연결하는 중입니다. 화면의 값은 마지막으로 받은 것입니다.」 | 네트워크가 끊겼거나 AAS 서버가 다시 시작되는 중입니다. | 잠시 기다립니다. 연결되면 화면이 저절로 갱신됩니다. 오래 이어지면 브라우저를 새로 고칩니다. |
| 「다른 창을 너무 많이 열어 이 창의 실시간 갱신을 멈췄습니다.」 | 같은 계정으로 AAS 창을 여러 개 열어 두었습니다. | 안 쓰는 창을 닫거나, 이 창에서 「이 창에서 계속」을 누릅니다. |
| 「○○ AI 에이전트 작업공간을 다시 시작하는 중입니다. 잠시 동안 목록·대화를 읽지 못할 수 있고, 끝나면 저절로 이어집니다.」 | 작업공간이 다시 시작되는 중입니다. | 기다립니다. 끝나면 이어집니다. |
| 채팅 목록에서 「AI 에이전트 작업공간을 준비하고 있습니다. 잠시 뒤 자동으로 나타납니다.」 | 처음 로그인했거나 작업공간을 방금 만들었습니다. | 잠시 기다립니다. |
| 채팅 목록에 「연결 없음」이 나옴 | 작업공간이 멈춰 있거나 연결되지 않았습니다. | 「다시 시도」를 누릅니다. 안 되면 「AI 에이전트 작업공간 화면에서 다시 시작」으로 이동해 다시 시작합니다. |
| 작업공간이 멈춰 있음 | 30일 동안 대화와 예약 작업 실행이 없으면 작업공간이 멈춥니다. | 「내 AI 에이전트 › AI 에이전트 작업공간」에서 멈춘 작업공간을 열어 다시 시작합니다. |
| 메뉴가 보이지 않음(변경 기록, 관리 묶음) | 그 화면은 권한이 있는 사람에게만 보입니다. | 변경 기록은 관리자, 작업공간 주인, 팀 관리자만 봅니다. 「관리」 묶음은 관리자만 봅니다. 필요하면 관리자에게 요청합니다. |
채팅과 대화
| 증상 | 원인 | 조치 |
|---|---|---|
| 「Hermes API 서버 연결이 끊겼습니다.」 또는 「AAS 서버가 다시 시작돼 이 화면의 연결이 끊겼습니다.」 | 대화 연결이 끊겼습니다. | 「다시 열기」를 누릅니다. 가장 최근 대화가 다시 열립니다. |
| 「연결을 기다리는 중입니다」, 「이 대화를 다시 여는 중입니다」 | 화면이 끊긴 대화를 저절로 다시 열고 있습니다. 간격을 늘려 가며 다시 시도합니다. | 기다립니다. 바로 열려면 「지금 다시 열기」를 누릅니다. 다시 연결되면 글을 보내거나 멈출 수 있습니다. |
| 「이 대화를 찾을 수 없습니다. 새 대화를 시작하세요.」 | 대화가 지워졌거나 찾을 수 없습니다. | 새 대화를 시작합니다. |
| 「보내지 못했습니다: …」 | 글을 보내는 중 오류가 났습니다. | 문구 뒤의 오류 내용을 읽고 다시 보냅니다. 같으면 관리자에게 전달합니다. |
| 보냈는데 답이 오지 않거나, 멈춘 것처럼 보임 | 승인이나 질문을 기다리고 있을 수 있습니다. | 대화 안의 「승인이 필요합니다」, 「AI 에이전트가 묻습니다」 카드와 상단 막대의 받은편지함에 숫자가 있는지 봅니다. 카드에 답하면 이어집니다. |
| 「승인 요청이 시간 초과로 끝났습니다. 명령을 실행하지 않았습니다」 | 정해진 시간 안에 답하지 않았습니다. | 명령은 실행되지 않았습니다. 같은 일을 AI 에이전트에게 다시 시킵니다. |
| 「안전장치가 막음」, 「안전장치가 위험한 명령을 막았습니다」 | 안전장치가 위험한 명령을 막았습니다. | 막힌 명령은 실행되지 않았습니다. 일을 다른 방식으로 시킵니다. 꼭 필요한 일인데 계속 막히면 관리자에게 문구를 전달합니다. |
| 진행 과정의 작업 단계에 「실패」 표시가 있음 | 도구 실행이 실패했습니다. | 진행 과정의 실패 단계를 열어 오류를 읽고, 같은 요청을 다시 보냅니다. |
자세한 설명은 2.7. 답이 막히거나 늦을 때와 2.6. 승인과 질문에 답하기를 봅니다.
파일 올리기와 받기
| 증상 | 원인 | 조치 |
|---|---|---|
| 파일을 올렸는데 AI 에이전트가 내용을 못 읽음 | 글자가 흐리거나 작은 스캔 문서이거나, 폴더를 올렸습니다. | 더 선명한 파일로 다시 올립니다. 폴더는 zip 으로 묶어 올리고, 읽지 못하면 파일을 하나씩 올립니다. 2.3. 파일 올리기와 받기를 봅니다. |
| 「한 메시지에 10개까지 붙일 수 있습니다」 | 파일을 10개보다 많이 붙였습니다. | 나눠서 보냅니다. |
| 「100MB 까지 올릴 수 있습니다」 | 파일이 100MB 를 넘습니다. | 파일을 줄이거나 나눕니다. |
| 「빈 파일은 올릴 수 없습니다」 | 파일 크기가 0 입니다. | 내용이 있는 파일을 올립니다. |
| 「폴더는 올릴 수 없습니다. zip 으로 묶어 올리세요」 | 폴더를 올렸습니다. | 폴더를 zip 으로 묶어 올립니다. |
| 「작업 폴더가 가득 찼습니다. 「파일」에서 지운 뒤 다시 올리세요」 | 작업 폴더의 저장 공간이 찼습니다. | 채팅 위쪽의 「파일」에서 안 쓰는 파일을 지운 뒤 다시 올립니다. |
| 「AI 에이전트 작업공간에 연결할 수 없습니다」 | 작업공간이 연결되지 않았습니다. | 위 「접속과 연결」 표를 따릅니다. |
| 「AI 에이전트 작업공간을 다시 시작한 뒤 쓸 수 있습니다」 | 화면의 안내 그대로입니다. | 관리자에게 작업공간을 다시 시작해 달라고 요청합니다. |
| 「다시 로그인하세요」 | 로그인이 끝났습니다. | 다시 로그인합니다. |
| 「AI 에이전트 작업공간 소유자가 올린 파일은 받을 수 없습니다」 | 작업공간 소유자가 올린 파일은 소유자가 아닌 사람이 받을 수 없습니다. | 소유자에게 직접 받습니다. |
자세한 설명은 2.3. 파일 올리기와 받기를 봅니다.
말로 입력과 읽어 주기
| 증상 | 원인 | 조치 |
|---|---|---|
| 「브라우저 알림에서 마이크를 허용하세요」 | 브라우저가 마이크 사용을 묻고 있습니다. | 브라우저 알림에서 「허용」을 누릅니다. |
| 「주소창 왼쪽의 사이트 정보 아이콘에서 마이크를 허용하세요」 | 마이크 사용을 막아 두었습니다. | 주소창 왼쪽의 사이트 정보 아이콘에서 마이크를 허용합니다. |
| 「마이크를 찾지 못했습니다」, 「다른 프로그램이 마이크를 쓰고 있습니다」 | 마이크가 연결되지 않았거나 다른 프로그램이 쓰는 중입니다. | 마이크를 연결하거나 다른 프로그램을 닫습니다. |
| 「소리가 들리지 않습니다. 마이크를 확인하세요」 | 소리가 입력되지 않습니다. | 마이크 설정과 음량을 확인합니다. |
| 「받아쓰지 못했습니다. 다시 시도를 눌러 주세요」 | 받아쓰기에 실패했습니다. | 「다시 시도」를 누릅니다. 「녹음 버리기」로 버릴 수도 있습니다. |
| 「지금 받아쓰기가 많습니다. 다시 시도를 눌러 주세요」 | 받아쓰기 요청이 몰렸습니다. | 잠시 뒤 「다시 시도」를 누릅니다. |
| 「녹음이 너무 깁니다. 짧게 나눠 말해 주세요」 | 한 번에 녹음할 수 있는 시간은 1분입니다. | 짧게 나눠 말합니다. |
| 「읽어 주지 못했습니다」, 「지금 읽기 요청이 많습니다」 | 읽어 주기에 실패했거나 요청이 몰렸습니다. | 잠시 뒤 다시 누릅니다. |
자세한 설명은 2.5. 말로 입력과 읽어 주기를 봅니다.
예약 작업
| 증상 | 원인 | 조치 |
|---|---|---|
| 예약 작업이 정해진 시각에 실행되지 않음 | 프로파일의 게이트웨이가 중지되어 있거나 작업이 꺼져 있습니다. 「예약 작업」의 「멈춘 작업」 보기의 「추정 원인」에 이유가 나옵니다. | 「자동화 › 메신저 연결」 표에서 게이트웨이가 「실행 중」인지 봅니다. 「중지됨」이면 관리자에게 시작을 요청합니다(요청 문장은 6.1. 예약 작업). 작업이 「꺼짐」이면 서랍에서 「켜기」를 누릅니다. |
| 아침 9시 작업이 다른 시각에 실행됨 | 「다음 실행」은 내 PC 의 시간대로 계산한 미리 보기이고, 실제 실행은 AAS 서버의 시간대를 기준으로 할 수 있습니다. | 관리자에게 서버의 시간대를 묻고 주기를 그 시각에 맞춰 바꿉니다. |
| 예약 작업 결과가 어디 있는지 모르겠음 | 「최근 실행」 목록에는 결과 글이 나오지 않습니다. | 결과를 받기로 정한 메신저를 봅니다. 「저장만」이면 「대화 › 채팅」의 지난 대화에서 출처를 「예약 작업」으로 거릅니다. 6.1. 예약 작업을 봅니다. |
| 작업이 실패했는데 알림이 오지 않음 | 「알림 없는 작업」 보기에 있으면 결과 전달 대상이 「저장만」입니다. | 서랍에서 결과 전달 대상을 메신저로 바꿉니다. |
| 「실패 중인 문제」가 계속 열려 있음 | 문제는 확인(ack)해야 닫힙니다. 지금 정상이어도 열려 있을 수 있습니다. | 문제는 관리자가 닫습니다. 서랍의 「확인(ack) 명령 복사」로 복사한 글을 관리자에게 보내 확인 처리를 요청합니다. 확인하지 않아도 작업은 계속 실행됩니다. 요청 문장은 6.1. 예약 작업의 「열린 문제 닫기」에 있습니다. |
| 서랍에 「이 AI 에이전트 작업공간의 주인, 팀 관리자, 관리자만 바꿀 수 있습니다.」가 나옴 | 작업을 바꿀 권한이 없습니다. | 작업공간 주인, 팀 관리 자, 관리자에게 요청합니다. |
| 이 주기는 N분마다 실행된다는 경고 | 실행 간격이 5분보다 짧습니다. | 실행마다 모델 호출 비용이 듭니다. 간격을 늘립니다. |
자세한 설명은 6.1. 예약 작업을 봅니다.
메신저 연결
| 증상 | 원인 | 조치 |
|---|---|---|
| 메신저에서 봇에게 말을 걸어도 답이 오지 않음 | 허용 사용자 칸이 비어 있고 승인도 하지 않았거나, 게이트웨이가 중지되어 있거나, 봇 토큰이 틀렸습니다. | 먼저 메신저 카드의 상태를 봅니다. 「승인 대기」가 있으면 「승인」을 누릅니다. 「게이트웨이 중지됨」이면 관리자에게 시작을 요청합니다. 「시작 실패」이면 봇 토큰을 새로 넣습니다. 승인한 뒤에는 봇에게 다시 말을 걸어 봅니다. |
| 봇 토큰을 어디서 받는지 모름 | 토큰은 메신저 서비스 쪽에서 발급합니다. | 관리자나 해당 메신저 서비스 담당자에게 받습니다. 메신저별 필요한 값은 6.2. 메신저 연결의 「연결에 필요한 값」에 있습니다. |
| 「저장하고 켜기」가 눌리지 않음 | 「필수 값」으로 표시된 칸이 비어 있습니다. | 필수 값을 모두 채웁니다. 슬랙은 봇 토큰과 앱 토큰 두 칸이 필요합니다. |
| 「봇 토큰이 맞는지 확인하세요.」 | 연결 시험이 실패했습니다. | 봇 토큰을 새로 넣고 다시 저장합니다. |
| 「이 프로파일의 게이트웨이가 꺼져 있습니다.」 | 게이트웨이가 중지되어 있습니다. | 관리자에게 게이트웨이 시작을 요청합니다. 요청 문장은 6.1. 예약 작업의 「게이트웨이가 중지되어 있을 때」에 있습니다. |
| 「필수 값이 비어 있습니다.」 | 필수 값이 들어 있지 않습니다. | 「필수 값」으로 표시된 칸을 채웁니다. |
| 「반영을 기다리는 중입니다.」 | 저장한 값이 아직 반영되지 않았습니다. | 잠시 뒤 「연결 시험」을 누릅니다. |
| 「저장했습니다. 이 환경은 게이트웨이를 다시 시작해야 반영됩니다.」 | 이 환경은 값을 바로 반영하지 않습니다. | 관리자에게 게이트웨이 다시 시작을 요청합니다. |
| 같은 봇이 두 곳에서 서로 연결을 빼앗음 | 같은 봇을 여러 프로파일에 넣었습니다. | 봇 하나는 프로파일 하나에만 연결합니다. |
자세한 설명은 6.2. 메신저 연결을 봅니다.
키·토큰과 비밀값
| 증상 | 원인 | 조치 |
|---|---|---|
| 「암호화되지 않은 주소(http)에서는 비밀값을 넣을 수 없습니다.」 | http 주소로 접속했습니다. | https 주소로 접속합니다. |
| 「API 키·토큰」 메뉴 옆에 숫자가 있음 | 만료되었거나 14일 안에 만료되는 키가 있습니다. | 「만료·만료 임박 」 카드를 눌러 해당 행을 확인하고, 새 키를 받아 「값 바꾸기」에서 넣습니다. |
| 값을 넣는 버튼이 보이지 않음 | 값을 넣는 일은 작업공간 주인, 팀 관리자, 관리자만 할 수 있습니다. | 주인이나 관리자에게 요청합니다. |
| 「이 화면에서 아직 바꿀 수 없습니다」 | secrets 폴더의 파일과 auth.json 은 이 화면에서 바꿀 수 없습니다. | 서랍의 안내 문구를 복사해 관리자에게 전달합니다. |
자세한 설명은 7.4. API 키·토큰과 4.4. 비밀값과 인증 파일을 봅니다.
Claude Code 연결과 계정
앞의 세 줄은 Claude Code 를 쓰는 개발자에게만 해당합니다(7.5. Claude Code 연결). 쓰지 않으면 건너뜁니다.
| 증상 | 원인 | 조치 |
|---|---|---|
| 「self-signed certificate in certificate chain」, 「unable to get local issuer certificate」 | PC 가 사내 인증서를 믿지 않습니다. | 오류 문구를 복사해 관리자에게 전달합니다. 관리자가 「Claude Code 연결」 화면의 「인증서 오류가 나면: 사내 인증서(CA) 등록하기」를 따라 등록합니다. 인증서 검사를 끄지 않습니다. |
| 「로그인을 켠 설치에서만 Claude Code 를 연결할 수 있습니다.」 | 로그인을 쓰지 않는 설치입니다. | 관리자에게 문의합니다. |
| 「연결은 10개까지입니다. 더 만들려면 안 쓰는 것을 끊으세요.」 | 연결과 토큰이 한도에 닿았습니다. | 안 쓰는 연결을 끊습니다. |
| Claude Code 가 갑자기 AAS 에 접속하지 못함 | 연결이 끝났거나 끊겼을 수 있습니다. 30일 동안 쓰지 않았거나, 내가 또는 관리자가 끊었을 수 있습니다. | 「설정 › Claude Code 연결」에서 목록을 확인하고, claude mcp login aas 로 다시 로그인합니다. |
| 비밀번호 변경 화면에 「이 로그인 방식에서는 AAS 에서 비밀번호를 바꿀 수 없습니다. 계정 관리자에게 문의하세요.」 | 회사 계정 시스템에서 비밀번호를 관리합니다. | 회사의 계정 관리자에게 문의합니다. |
자세한 설명은 7.5. Claude Code 연결과 7.6. 회사 정보와 내 정보를 봅니다.