자주 묻는 질문과 문제 해결

실습하다 막히기 쉬운 곳과 해결 방법, 그리고 용어 정리입니다.

설치와 실행#

macOS에서 “손상되었기 때문에 열 수 없습니다” / “확인되지 않은 개발자”라고 나옵니다.

서명되지 않은 배포판이라 그렇습니다. 앱을 오른쪽 클릭 › 열기, 또는 시스템 설정 › 개인정보 보호 및 보안 › 「그래도 열기」. 그래도 안 되면 xattr -dr com.apple.quarantine "/Applications/Ontological Studio.app"(1장).

Windows에서 SmartScreen이 막습니다.

「추가 정보 › 실행」을 누릅니다.

홈에 「에이전트 설정 필요」가 보입니다.

Claude Code 또는 Codex CLI를 설치하고 터미널에서 한 번 로그인하세요. 그다음 메뉴 런타임 › 에이전트에서 고르거나 앱을 다시 켭니다. CLI 없이 쓰려면 「설정」에서 studio.env에 OPENAI_API_KEY를 넣습니다.

처음 상태로 되돌리고 싶습니다.

앱을 끄고 데이터 폴더(macOS ~/Library/Application Support/Ontological Studio/)를 지운 뒤 다시 켭니다. 예제 DB와 예제 온톨로지가 새로 만들어집니다. 내가 만든 온톨로지·앱도 함께 지워지니 주의하세요.

앱을 끄는 데 몇 초 걸립니다.

정상입니다. 데이터베이스를 안전하게 닫고 서비스들을 차례로 내립니다.

데이터소스와 Cypher#

포털에서 예제 노드가 안 보입니다.

왼쪽 위 그래프 선택이 sample인지 확인하세요. 예제의 가상 노드는 sample 그래프에 있습니다. 구축한 온톨로지는 ontology 그래프에 있습니다(4장).

unknown function 'date' 오류가 납니다.

date() 함수는 아직 없습니다. 날짜 컬럼은 '2026-08-29' 같은 문자열과 바로 비교하세요.

관계 패턴을 썼는데 결과가 비어 있습니다.

관계 이름과 양쪽 노드의 라벨을 모두 적었는지 확인하세요. 가상 관계는 -[r]->처럼 이름 없이 찾으면 결과가 나오지 않습니다. 방향(->, <-)도 확인하세요.

invalid input syntax for type bigint 오류가 납니다.

소수 타입 컬럼의 합계를 WITH … WHERE로 다시 거를 때 나는 알려진 문제입니다. sum(toFloat(x))로 바꿔 쓰세요(8장).

EXISTS { … }가 안 됩니다.

하위 질의는 아직 없습니다. OPTIONAL MATCH … WITH … WHERE x IS NULL로 씁니다.

가상 노드에 값을 넣으려고 하니 read-only라고 합니다.

가상 노드는 원천 테이블을 비춘 것이라 읽기 전용입니다. 값은 원천 시스템에서, Ontological Studio에서는 액션으로 바꿉니다(6장).

가상 노드를 지울 수 없습니다.

그 노드를 잇는 가상 관계부터 지우세요. 오류 메시지에 남은 관계 이름이 나옵니다.

원천 DB 연결이 실패합니다.

호스트·포트에 이 PC에서 접속할 수 있는지, 계정에 그 스키마를 읽을 권한이 있는지 확인하세요. 데이터소스 이름은 영문 소문자·숫자·밑줄만 됩니다. Windows판은 지금 PostgreSQL만 됩니다.

구축과 질의#

구축이 끝났는데 질의에서 “발행된 온톨로지가 없다”고 합니다.

발행하지 않았기 때문입니다. 구축 대화창에 “발행해 줘”라고 지시하세요(12장).

같은 문서로 다시 구축했더니 클래스 이름이 다릅니다.

에이전트(LLM)가 설계하므로 이름은 조금씩 다를 수 있습니다. 골든 퀘스천에 같은 답을 내는지로 판단하세요. 원하는 이름이 있으면 구축 의도에 적어 두거나, 「정보」 탭에서 직접 고치세요.

에이전트의 답이 틀린 것 같습니다.

답에 적힌 근거를 보고, 같은 질문을 포털에서 Cypher로 검산하세요. 온톨로지에 필요한 개념이나 관계가 없다면 골든 퀘스천에 그 질문을 넣고 다시 구축합니다.

예제 Supplier와 내가 만든 Supplier가 섞입니다.

클래스 이름은 온톨로지(스키마)를 넘어 전역입니다. 같은 이름의 클래스를 다른 온톨로지에서 만들면 인스턴스가 한 라벨에 섞입니다. 실습용 온톨로지에서는 QualitySupplier처럼 다른 이름을 쓰거나 구축 의도에 이름을 지정하세요.

액션#

계획을 세웠는데 대상이 0건입니다.

조건에 맞는 대상이 없거나, 모두 정책으로 거부된 것입니다. 계획 카드의 거부 사유를 보세요. 대상 0건인 계획은 실행되지 않습니다.

“실행해”라고 했는데 실행되지 않습니다.

계획 카드에서 먼저 「승인」을 눌렀는지 확인하세요. 에이전트는 승인할 수 없습니다. 계획이 만료됐다면 다시 지시해 계획을 새로 세웁니다.

취소했는데 일부만 되돌아갔습니다.

보상 이력에서 실패한 단계를 보세요(⚠ 보상 실패). 업무 시스템이 그 사이 다른 이유로 상태를 바꿨다면 보상이 거절될 수 있습니다. 그런 건은 담당자가 업무 시스템에서 직접 확인해야 합니다.

용어#