문제 해결

이 장에서 배우는 것 증상별로 무엇을 어떤 순서로 확인하는지, 그리고 도움을 요청할 때 무엇을 챙겨 가야 하는지.

먼저 세 가지

증상이 무엇이든 이 셋부터 봅니다. 절반 이상이 여기서 끝납니다.

text

□ 크레딧이 남아 있나        → 사용량 화면□ 이 워크스페이스가 맞나     → 왼쪽 위 이름 확인□ 새로고침 해봤나           → 화면만의 문제인 경우가 많습니다

두 번째가 의외로 흔합니다. 워크스페이스를 여러 개 쓰면 자료도 도구도 다른 곳에 있습니다.

대화

답이 안 옵니다 / 도중에 멈춥니다

text

1. 새로고침                → 화면 연결만 끊긴 경우2. 크레딧 확인             → 소진되면 새 요청이 시작되지 않습니다3. 같은 질문 다시           → 일시적 오류면 여기서 해결4. 도구를 쓰는 작업인가     → 아래 "도구" 항목으로

1번이 자주 통합니다. 실시간 전달은 손실될 수 있게 설계되어 있고, 대신 내용은 서버에 먼저 저장됩니다. 화면이 끊겨도 새로고침하면 이어서 보입니다.

답은 오는데 내용이 이상합니다

증상	먼저 볼 곳
사내 자료를 모릅니다	드라이브에 그 파일이 올라가 있나
있는 자료인데 못 찾습니다	파일이 텍스트로 읽히는 형태인가 (스캔 이미지 PDF는 못 읽습니다)
오래된 정보로 답합니다	드라이브의 파일이 예전 버전인가
앞서 말한 규칙을 잊습니다	대화가 길어진 경우 — 정리하고 새 대화로
매번 다르게 답합니다	지시에 완료 조건이 없는 경우

마지막 두 줄은 컨텍스트가 밀려날 때와 좋은 지시의 네 가지 요소에서 다룬 내용입니다.

에이전트와 도구

도구를 안 씁니다

text

1. 그 도구가 켜져 있나        → 도구 설정 화면에서 확인2. 켜져 있는 도구가 너무 많나  → 비슷한 게 여럿이면 엉뚱한 걸 고릅니다3. 언제 쓰는 도구인지 설명이 있나 → 설명이 부실하면 안 부릅니다4. 지시에서 명시해보기        → "검색 도구를 써서 확인해줘"

1번은 도구 켜고 끄기에서 봅니다.

3번이 자주 원인입니다. 도구 설명은 사람이 아니라 모델이 읽습니다. "무엇을 하는지"만 있고 "언제 부르는지"가 없으면 잘 안 불립니다.

MCP 서버가 연결되지 않습니다

text

□ 주소가 정확한가            (끝의 경로까지)□ 자격증명이 만료되지 않았나  (OAuth 토큰은 만료됩니다)□ 그 서버가 지금 살아 있나    (제공자 상태 페이지)□ 도구 목록이 비어 있나       → 연결은 됐는데 권한이 좁은 경우

마지막 줄이 헷갈립니다. 연결 성공인데 쓸 수 있는 도구가 하나도 없으면, 대개 발급한 토큰의 권한이 좁은 것입니다.

도구는 부르는데 결과가 비어 옵니다

권한 문제일 가능성이 높습니다. 읽기 권한만 있는 계정으로 쓰기 도구를 부르면 조용히 빈 결과가 오는 서버가 있습니다. 도구는 권한이다의 첫 번째 질문 — "이 서버가 닿는 범위는 어디까지인가"로 돌아가세요.

시스템

시스템이 오프라인으로 표시됩니다

text

1. 그 컴퓨터가 켜져 있나2. HyperTeams가 실행 중인가3. 네트워크가 바뀌지 않았나4. 토큰이 회수되지 않았나

2번이 의심되면 HyperTeams 문제 해결로 가세요.

연결 상태는 주기적인 신호로 판단합니다. 그래서 컴퓨터를 껐다 켜면 잠깐 오프라인으로 보이다가 다시 붙습니다. 몇 분 기다려보세요.

작업이 끝나지 않은 채 남아 있습니다

오래 걸리는 작업은 정상입니다. 다만 컴퓨터가 꺼지거나 프로그램이 재시작되면 진행 중이던 작업이 주인을 잃습니다. 이런 작업은 시간이 지나면 자동으로 종료 처리되지만, 결과는 남지 않습니다. 다시 시켜야 합니다.

긴 작업은 중간 산출물을 파일로 남기게 지시하세요. 그러면 중단돼도 처음부터 다시 하지 않습니다.

터널 관련 기능만 안 됩니다

터널은 시스템에 붙는 별도 부가 기능입니다. 만료되면 주소 관리만 막히고 상태 확인·명령 실행은 그대로 됩니다. "일부만 안 되는" 증상이면 여기를 보세요.

밖에서 들어오는 길

채널·위젯·이메일로 보냈는데 반응이 없습니다

text

1. 어느 워크스페이스로 연결했나  → 다른 곳에 도착해 있을 수 있습니다2. 연결이 활성 상태인가3. 크레딧이 남아 있나           → 소진되면 외부 요청도 멈춥니다4. 담당 에이전트가 지정되어 있나

1번을 먼저 확인하세요. 채널과 위젯은 워크스페이스 단위로 연결됩니다.

예약과 큐

예약한 시각에 안 돌았습니다

text

□ 예약이 활성 상태인가□ 시간대(타임존) 설정이 맞나□ 대상 시스템이 그 시각에 온라인이었나□ 크레딧이 그 시각에 남아 있었나□ 앞선 실행이 아직 안 끝났나  → 겹치면 밀립니다

마지막 줄이 자주 원인입니다. 매시간 예약인데 실행이 90분 걸리면 계속 밀립니다. 큐와 예약에서 주기를 조정하세요.

비용

사용량이 갑자기 늘었습니다

이 순서로 좁힙니다.

text

1. 사용량 화면에서 분포 확인   → 총액이 아니라 누가·무엇이2. 특정 사용자에 몰렸나        → 그 사람의 최근 대화 확인3. 특정 시각에 몰렸나          → 예약 작업 확인4. 특정 에이전트에 몰렸나      → 도구 반복 호출 가능성

3번과 4번이 큰 사고를 냅니다. 예약 작업이 실패하고 재시도를 반복하거나, 에이전트가 같은 도구를 계속 부르는 경우입니다. 자세한 절감 순서는 사용량과 크레딧에 있습니다.

권한

화면이 안 보입니다 / 버튼이 없습니다

거의 항상 역할 문제입니다.

안 보이는 것	필요한 역할
멤버·도구·시스템 관리 화면	admin 이상
시스템 등록·정책 변경	owner만
결제·워크스페이스 삭제	owner만

멤버와 역할의 표를 그대로 보세요.

그래도 안 되면

도움을 요청할 때 이 다섯 가지를 챙기면 해결이 훨씬 빠릅니다.

text

□ 워크스페이스 이름□ 해당 대화(스레드) 링크□ 발생 시각 (대략이라도)□ 무엇을 시켰고 무엇이 나왔는지□ 재현되나 — 다시 해도 같은 증상인가

마지막 줄이 가장 중요합니다. 한 번만 그런 것과 매번 그런 것은 원인이 완전히 다릅니다.

확인

1. 답변이 도중에 멈췄을 때 새로고침이 자주 통하는 이유는?

답

내용은 서버에 먼저 저장되고 화면 전달은 손실될 수 있게 설계되어 있기 때문입니다. 실시간 연결이 끊겨도 내용 자체는 남아 있어 새로고침하면 이어서 보입니다.

2. 도구를 켰는데도 에이전트가 안 부르는 흔한 이유는?

답

도구 설명에 "언제 부르는지"가 없기 때문입니다. 설명은 사람이 아니라 모델이 읽습니다. 무엇을 하는지만 있고 호출 조건이 없으면 잘 안 불립니다. 켜진 도구가 너무 많아 비슷한 것끼리 헷갈리는 경우도 있습니다.

3. 매시간 예약인데 실행이 계속 밀리는 이유는?

답

앞선 실행이 주기보다 오래 걸리기 때문입니다. 실행이 90분 걸리는데 매시간 예약이면 계속 겹쳐서 밀립니다. 주기를 늘리거나 작업을 쪼개야 합니다.

여기까지가 Connect입니다. 개념부터 다시 보려면 Connect는 무엇인가, 용어가 헷갈리면 용어집으로 가세요.