본문으로 건너뛰기

A.2. 문제 해결

개요​

이 장은 관리자가 만나는 증상을 증상, 확인, 조치 순서로 정리합니다. 서랍은 화면 오른쪽에서 열리는 상세 창입니다. 화면에 나온 문구가 있으면 그 문구로 증상을 찾습니다.

권한: 관리자. 일부 조치는 관리자가 할 수 없습니다. 그 행의 「조치」 칸은 「[운영자]」로 시작합니다.

운영자는 AAS 를 설치하고 서버를 관리하는 사람입니다(A.3. 용어 사전). 「[운영자]」 표시가 있는 행은 운영자에게 알립니다. 알릴 때는 증상 문구, 어느 사용자나 작업공간인지, 「버전 정보」 창의 버전·커밋 해시·빌드 날짜를 함께 전합니다. 확인 방법은 8.2. 설치와 버전을 봅니다. 설치 중 문제는 COP 설치 가이드의 AAS 설치 장에 있습니다.

AI 에이전트 작업공간​

AI 에이전트 작업공간은 사용자마다 하나씩 만들어지는 AI 에이전트의 일터입니다. 먼저 왼쪽 메뉴의 「내 AI 에이전트 › AI 에이전트 작업공간」에서 그 사용자의 「상태」 열과 「메시지」 열을 봅니다.

증상확인조치
작업공간이 「준비 중」이나 「만드는 중」에서 오래 바뀌지 않습니다.「메시지」 열의 이유와 상태 옆 표시를 봅니다. 「노드 자리 기다리는 중」이 있는지 봅니다.만든 직후에는 몇 분 기다립니다. 「노드 자리 기다리는 중」이면 3.5. 작업공간 크기와 노드 여유를 봅니다. 그래도 같으면 [운영자] 메시지를 알립니다.
작업공간 상태가 「실패」입니다.「메시지」 열에 자원 한도 초과가 있는지 봅니다.3.2. 작업공간 상태와 다시 시작을 따릅니다. 자원 한도 초과이면 [운영자] 자원 한도를 늘려 달라고 요청합니다.
작업공간 상태가 「멈춤」입니다.서랍의 「멈춘 이유」를 봅니다. 「오래 쓰지 않아 멈춤」「OIDC 그룹에서 빠져 멈춤」「관리자가 멈춤」 중 하나입니다.서랍의 「다시 시작」을 누릅니다. 이유가 그룹 탈퇴나 사용 중지이면 그 원인을 먼저 풉니다. 성공하면 상태가 「사용할 수 있음」으로 바뀝니다.
작업공간 상태가 「연결 끊김」입니다.새 버전으로 바꾸는 중인지, 몇 분이 지났는지 봅니다.몇 분 기다립니다. 계속되면 [운영자] 작업공간 이름과 「메시지」를 알립니다.
새 버전으로 바꾸는 중인 작업공간이 끝나지 않습니다.상태 옆에 「업데이트 중」이 있는지, 위 띠의 단계를 봅니다.3.3. 사용자 Hermes 새 이미지 롤아웃의 「실패했을 때」를 따릅니다.
사용자가 로그인은 되는데 작업공간이 없다고 합니다.「AI 에이전트 작업공간」 화면에 그 사람의 작업공간이 있는지, 사람별 개수 한도가 0 개가 아닌지 봅니다.한도가 0 개이면 3.1. 작업공간 목록과 개수 한도에서 늘립니다. 한도가 충분한데 없으면 [운영자] 사용자 이메일을 알립니다.
사용자가 한도 때문에 작업공간을 만들 수 없다고 합니다.사용자 화면에 「한도 {n}개에 도달했습니다」가 있는지 봅니다.작업공간 서랍의 「이 사람의 설정」에서 「작업공간 개수」를 늘립니다. 3.1. 작업공간 목록과 개수 한도를 봅니다.

게이트웨이와 예약 작업​

게이트웨이는 AI 에이전트가 메신저와 예약 작업을 받는 통로입니다. 게이트웨이를 켜고 끄는 일은 관리자만 합니다.

증상확인조치
사용자가 텔레그램·슬랙으로 말을 걸어도 AI 에이전트가 답하지 않습니다.「자동화 › 메신저 연결」에서 그 프로파일의 게이트웨이가 「중지됨」인지 봅니다. 채팅 화면에는 「게이트웨이 중지됨」이 나옵니다.프로파일의 「개요」 탭 「게이트웨이」 구역에서 「시작」을 누릅니다. 성공하면 「실행 중」으로 바뀝니다. 「실행 중」인데 끊겨 있으면 「채널」 탭에서 다시 연결합니다. 7.1. 운영 점검의 3단계를 봅니다.
예약 작업이 정해진 시각에 실행되지 않습니다.「메신저 연결」 화면에 「게이트웨이가 중지되어 있어 실행되지 않습니다」가 있는지 봅니다. 「예약 작업」의 「멈춘 작업」 탭, 「기록 › 변경 기록」의 「작업을 중지함」도 봅니다.게이트웨이가 중지됐으면 시작합니다. 작업이 중지돼 있으면 다시 시작합니다. 작업공간이 「멈춤」이면 위 표를 따릅니다. 모두 정상인데 실행되지 않으면 [운영자] 작업 이름과 시각을 알립니다.
예약 작업이 계속 실패합니다.「예약 작업」의 「마지막 실행 실패」 탭에서 행을 열어 실패 이유를 봅니다.이유에 모델 문제가 있으면 아래 「모델과 답」 표를 봅니다. 이유가 설정이나 지시문 문제이면 작업을 고칩니다. 7.1. 운영 점검의 2단계를 봅니다.
채널용 키를 바꿨는데 메신저에 적용되지 않습니다.키를 바꾼 뒤 게이트웨이를 다시 시작했는지 봅니다.프로파일 「개요」 탭의 「게이트웨이」 구역에서 「재시작」을 누릅니다. 채널용 값은 재시작해야 적용됩니다.

공지​

증상확인조치
올린 공지가 사용자에게 보이지 않습니다.「관리 › 공지」 화면에서 그 공지가 「보이는 중」 카드에 있는지 봅니다. 「예정」이나 「끝남」이면 기간이 맞지 않는 것입니다.시작과 끝 시각을 고치거나 「1시간 연장」을 누릅니다. 시작과 끝 시각이 되면 약 6초 안에 나타나고 사라집니다.
공지에 「대상 부서가 없어짐」이 붙어 있습니다.대상이던 부서를 지웠는지 봅니다.이 공지는 아무에게도 보이지 않습니다. 「복사해서 새로 만들기」로 대상을 다시 정합니다.
일부 사용자에게만 공지가 안 보입니다.그 사용자의 부서가 대상 부서에 들어 있는지 봅니다. 부서가 없는 사람에게는 「전체」 공지만 보입니다.대상을 「전체」로 바꾸거나 사용자의 부서를 정합니다.
사용자가 공지를 본 적이 없다고 합니다.사용자가 닫았는지 봅니다. 닫은 공지는 계정 메뉴의 「지금 공지 {n}」에 있습니다. 로그인 화면에는 공지가 나오지 않습니다.사용자에게 계정 메뉴의 「다시 화면 맨 위에 보이기」를 안내합니다. 내용을 고쳤으면 「닫은 사람에게 다시 보이기」를 켜고 저장합니다.

모델과 답​

증상확인조치
사용자가 AI 에이전트가 답하지 않는다고 합니다.순서대로 봅니다. 그 작업공간의 상태가 「사용할 수 있음」인지, 대시보드 「운영 정보」가 「LiteLLM 정상」인지, 프로파일의 모델이 「LiteLLM 에 없음」이 아닌지, 「설정 › API 키·토큰」에 만료된 값이 없는지 봅니다.작업공간이 멈췄으면 다시 시작합니다. 「LiteLLM 연결 안 됨」이면 [운영자] 알립니다. 모델이 「LiteLLM 에 없음」이면 3.4. 프로파일 모델과 설정 대신 고치기에서 모델을 바꿉니다. 키가 만료됐으면 새 값을 넣습니다.
사용자가 모델을 못 바꾼다고 합니다.모델은 관리자만 바꿉니다. 받은편지함의 「관리자에게 온 요청」에 요청이 있는지 봅니다.프로파일 상세 창의 「개요」 탭에서 주 모델을 바꾸고 「처리했습니다」를 누릅니다. 들어줄 수 없으면 「거절」을 누르고 사유를 적습니다. 5.3. 사용자 요청 처리를 봅니다.
사용자 화면에 「처리 대기 중({n}일째)」이 계속 남습니다.받은편지함에 그 요청이 아직 처리되지 않고 있는지 봅니다.「처리했습니다」나 「거절」을 눌러야 사라집니다. 7일 넘은 요청은 호박색 선이 붙어 있습니다.
사용자가 채팅 질문이 거절된다고 합니다.가드레일이 막은 질문인지 봅니다.4.2. 안전장치를 따릅니다.

로그인과 권한​

증상확인조치
사용자가 「사용자·권한」이나 「역할 템플릿」, 「공지」 메뉴가 안 보인다고 합니다.그 사람이 관리자인지 「사용자·권한」 화면의 「관리자」 카드에서 확인합니다.관리자가 아니면 정상입니다. 관리자가 필요한 사람이면 「사용자·권한」에서 관리자로 지정합니다. 지정 직후에도 보이지 않으면 다시 로그인하게 합니다.
화면에 「관리자만 볼 수 있는 화면입니다. 사용자 추가와 권한 변경은 관리자에게 요청하세요.」가 나옵니다.주소로 직접 관리 화면에 들어간 일반 사용자입니다.필요한 일을 관리자에게 요청하게 합니다.
「사용자·권한」 화면에 「Claude Code 연결」 탭이 없습니다.화면 제목 아래에 「로그인이 꺼져 있습니다」가 있는지 봅니다.로그인을 켠 설치에서만 이 탭이 나옵니다. [운영자] 로그인 설정을 요청합니다. 8.1. 연동 서비스 구성을 봅니다.
사용자가 AAS 에 들어가지 못합니다.「사용자·권한」 화면의 「AAS 접근 없음」과 「OIDC 계정 없음」 카드에 그 사람이 있는지 봅니다.2.4. 접근 없음과 계정 없음 정리를 따릅니다.
변경 기록 메뉴가 안 보인다고 합니다.그 사람이 관리자, 작업공간 주인, 팀 관리자인지 봅니다.이 세 구분이 아니면 메뉴가 없습니다. A.1. 권한 표를 봅니다.

스킬 허브​

증상확인조치
「스킬 허브 주소가 설정돼 있지 않습니다」가 나옵니다.스킬 허브가 연결되지 않은 설치입니다.[운영자] 스킬 허브 설정을 요청합니다.
「설치 도우미가 응답하지 않습니다」가 나오고 설치가 끝나지 않습니다.대시보드 「운영 정보」에 「스킬 허브 배달기 멈춤」이 있는지 봅니다.[운영자] AAS 서버 상태 확인을 요청합니다. 설치 요청은 대기열에 남아 있고 도우미가 다시 돌면 처리됩니다.
「이 AI 에이전트 작업공간은 허용이 필요한 네임스페이스 '제한' 을 받을 수 없습니다」가 나옵니다.패키지가 「제한」 네임스페이스에 있는지, 이 AI 에이전트 작업공간에 허용했는지 봅니다.관리자가 그 AI 에이전트 작업공간으로 바꾼 뒤 「'제한' 허용하기」를 누릅니다. 6.1. 스킬 허브와 네임스페이스를 봅니다.
「스킬 허브에 연결하지 못해 새 버전을 확인하지 못했습니다」가 나옵니다.「스킬 허브」의 다른 탭에서 목록이 읽히는지 봅니다. 대시보드의 「스킬 허브 배달기」도 봅니다.「다시 확인」을 누릅니다. 계속되면 [운영자] 허브 상태 확인을 요청합니다.
「새 버전 있음」 탭의 상태가 「직접 고친 내용 있음」이라 자동으로 올라가지 않습니다.사용자가 그 스킬을 직접 고쳤는지 봅니다.줄을 열어 「고친 것은 따로 보관하고 업그레이드」나 「새 버전으로 덮어쓰기」를 고릅니다. 6.3. 기본 스킬과 새 버전 알림을 봅니다.
「업그레이드할 수 없음: 관리자 허용 필요」가 나옵니다.패키지가 「제한」 네임스페이스인지 봅니다.그 AI 에이전트 작업공간에 「제한」을 허용합니다.
「업그레이드할 수 없음: 공용 프로파일」이 나옵니다.공용 프로파일은 새 버전 올리기의 대상이 아닙니다.조치가 필요 없습니다.
자동 업그레이드가 켜져 있는데 기본 스킬이 올라가지 않았습니다.상태가 「자동 업그레이드 실패」인지, 고친 내용이 있는지 봅니다. 새 버전이 허브에 올라간 지 몇 분이 지났는지도 봅니다.실패면 줄을 열어 직접 올립니다. 새 버전은 허브 반영 뒤 몇 분 뒤에 나옵니다.
게시 요청이 「스킬 허브 검토 중」에서 바뀌지 않습니다.허브가 자체 검토 중인 상태입니다.AAS 에서 승인할 수 없습니다. 허브의 검토가 끝나기를 기다립니다. 6.2. 게시 요청 검토를 봅니다.
게시 승인에서 「사내 도메인이나 사설 IP 가 있어 공개 네임스페이스에 게시할 수 없습니다」가 나옵니다.상세 창의 경고에 나온 파일과 줄을 봅니다.요청한 사용자에게 사내 주소를 빼고 다시 요청하게 합니다. 구성원에게만 보여도 되면 「제한」을 고릅니다.
게시 요청 상태가 「게시 실패」입니다.상세 창의 「결과」 칸에 나온 메시지를 봅니다.원인을 고친 뒤 같은 요청을 다시 승인합니다.
직접 게시 결과가 「결과를 아직 모릅니다」로 나옵니다.「게시 요청」 탭에서 그 행을 열고, 패키지 목록에 새 버전이 있는지 봅니다.「같은 묶음으로 다시 게시」를 누릅니다. 허브에 이미 있는 버전이면 기록만 맞춥니다.
「AAS 기본 스킬은 AAS 서버가 관리합니다」가 나옵니다.게시하거나 숨기려는 이름이 AAS 기본 스킬인지 봅니다.화면에서는 할 수 없습니다. 기본 스킬은 AAS 서버를 새 버전으로 반영해야 바뀝니다. [운영자] 변경이 필요하면 요청합니다. 6.3. 기본 스킬과 새 버전 알림을 봅니다.

점검과 모니터링​

증상확인조치
대시보드 숫자 카드에 숫자 대신 줄 표시(-)가 나옵니다.숫자 카드 아래에 「다음 수집」 시각이 있는지 봅니다.첫 수집 전입니다. 시각이 지난 뒤 다시 엽니다.
표에 「수집 실패 · 시각 값」이 나옵니다.그 AI 에이전트 작업공간의 「준비」 열이 「준비됨」인지 봅니다.이전에 수집한 값을 보여 주는 중입니다. 작업공간 상태를 확인합니다. 3.2. AI 에이전트 작업공간 상태와 다시 시작을 봅니다.
대시보드 「운영 정보」에 「LiteLLM 연결 안 됨」이 나옵니다.「내 AI 에이전트 › 모델」에서 「LiteLLM 확인 불가」가 나오는지 봅니다.[운영자] 모델 서버 확인을 요청합니다. 4.1. 모델을 봅니다.
메뉴의 「예약 작업」에 빨간 숫자가 있습니다.「예약 작업」의 「마지막 실행 실패」와 「멈춘 작업」 탭을 봅니다.7.1. 운영 점검을 따릅니다.
변경 기록이 비어 있습니다.오른쪽 위의 기간을 7일로 골랐는지 봅니다. 처음에는 30일입니다. 주인 화면이면 현재 주인이 된 뒤의 기록만 나옵니다.기간을 30일로 바꿉니다.

음성​

받아쓰기와 읽어 주기는 설치할 때 켠 경우에만 쓸 수 있습니다. 구성은 8.1. 연동 서비스 구성을 봅니다.

증상확인조치
사용자가 「말로 입력」 버튼이 없다고 합니다. 또는 「지금 받아쓰기가 많습니다. 다시 시도를 눌러 주세요」가 자주 나옵니다.다른 사용자의 입력칸에도 버튼이 없는지, 안내가 몇 번이나 나오는지 봅니다.[운영자] 받아쓰기를 켠 설치인지, 서버가 바쁜지 확인을 요청합니다. 안내만 나올 때는 잠시 뒤 다시 시도하게 합니다.
「AI 에이전트 작업공간이 연결되지 않아 말로 입력을 쓸 수 없습니다」가 나옵니다.그 사용자의 작업공간 상태가 「사용할 수 있음」인지 봅니다.위 「AI 에이전트 작업공간」 표를 따릅니다. 준비되면 쓸 수 있습니다.

Claude Code 연결​

증상확인조치
사용자가 연결 중 인증서 오류(「self-signed certificate in certificate chain」)를 만납니다.사내 인증서(CA)를 PC 가 믿는지 봅니다.사용자 매뉴얼의 인증서 오류가 날 때를 따릅니다. 사용자의 「설정 › Claude Code 연결」에 같은 안내가 있습니다. 회사에서 관리하는 PC 에서만 하도록 안내합니다.
「연결은 10개까지입니다」가 나옵니다.사용자의 연결 목록에서 쓰지 않는 것을 찾습니다.안 쓰는 연결을 끊게 합니다. 관리자는 「사용자·권한」의 「Claude Code 연결」 탭에서 끊을 수 있습니다.
관리자가 Claude Code 로 사용자 관리 같은 관리 일을 하려는데 거절됩니다.연결로 하는 일은 관리자 권한을 쓰지 못합니다.브라우저로 로그인해서 합니다. 7.4. Claude Code 연결 관리를 봅니다.
「로그인을 켠 설치에서만 Claude Code 를 연결할 수 있습니다」가 나옵니다.로그인을 끈 설치입니다.[운영자] 로그인 설정을 요청합니다.

설치와 서버​

아래 증상은 운영자가 고칩니다. 관리자는 증상을 정확히 전달합니다.

증상확인조치
로그인 화면이 AAS 용이 아닌 기본 로그인 서버 화면으로 나옵니다.모든 사용자에게 같은지 봅니다.[운영자] 화면을 캡처해 알립니다.
AAS 화면이 열리지 않거나 사용자 작업공간이 시작하지 못합니다.대시보드가 열리는지, 「AI 에이전트 작업공간」 화면의 「메시지」를 봅니다.[운영자] 증상과 메시지를 알립니다.
사용자 Hermes 가 새 버전으로 바뀌지 않습니다.3.3. 사용자 Hermes 새 이미지 롤아웃의 「실패했을 때」를 봅니다.이유를 모르겠으면 [운영자] 「자세히」의 메시지를 알립니다.

관련 문서​