GitHub 저장소 onyx-dot-app/onyx를 초보자 관점에서 풀어쓴 안내서입니다. Onyx는 채팅 화면 하나에 사내 지식 검색, 웹 검색, 에이전트, 코드 실행, 파일 생성 같은 기능을 붙여 주는 오픈소스 AI 플랫폼입니다.
그냥 챗봇 앱인지, AI 운영 플랫폼인지부터 구분하기.
Onyx는 스스로를 “LLM을 위한 애플리케이션 레이어”라고 설명합니다. 쉽게 말하면, OpenAI·Anthropic·Gemini·Ollama 같은 여러 AI 모델을 그냥 API로 부르는 데서 끝내지 않고, 사람이 일할 수 있는 화면과 기능을 얹어 주는 층입니다.
초보자에게는 이렇게 이해하면 편합니다. ChatGPT 같은 대화창은 “AI와 말하는 창”에 가깝습니다. Onyx는 거기에 회사 문서 검색, 웹 검색, 에이전트 행동, 코드 실행, 파일 생성을 한곳에 묶으려는 제품입니다.
Onyx를 가장 짧게 이해하는 방법.
모델 하나를 고르는 제품이라기보다, 어떤 모델을 쓰든 그 위에 채팅·검색·에이전트·문서 연결·권한 관리를 붙이는 제품에 가깝습니다.
그래서 관심 포인트도 “답변을 잘하나?” 하나가 아니라 “우리 자료를 연결할 수 있나?”, “팀 권한을 나눌 수 있나?”, “직접 배포할 수 있나?”로 넓어집니다.
README와 문서에서 반복해서 강조하는 기능들.
Onyx의 기능은 한 단어로 줄이면 “AI 채팅 고도화”입니다. 하지만 실제로는 여러 기능이 붙어 있습니다. 아래 항목은 각각 독립 기능이면서, 함께 쓰면 팀의 지식 작업 흐름이 됩니다.
Onyx는 문서나 연결된 앱의 내용을 색인(index)으로 만들고, 질문이 들어오면 관련 자료를 찾아 답변에 활용합니다. README는 이를 하이브리드 인덱스와 AI 에이전트를 결합한 정보 검색으로 설명합니다.
단순히 한 번 검색하고 끝내는 것이 아니라, 여러 단계로 조사 흐름을 진행해 더 깊은 보고서를 만드는 기능입니다. README는 Onyx의 Deep Research가 별도 벤치마크에서 좋은 성과를 냈다고 소개합니다.
사용자는 지시사항, 지식, 액션을 조합해 특정 업무용 에이전트를 만들 수 있습니다. 예를 들어 “고객 문의 초안 작성”, “문서 검색 담당”, “데이터 분석 보조” 같은 역할을 따로 줄 수 있습니다.
웹 검색으로 최신 정보를 가져오고, 문서나 그래픽 같은 산출물을 만들고, 샌드박스에서 코드를 실행해 계산·그래프·파일 수정을 할 수 있습니다. 일반 채팅 앱보다 “작업 도구”에 가까워지는 부분입니다.
Onyx는 특정 모델 하나에만 묶이지 않는 구조를 지향한다.
README에 따르면 Onyx는 주요 LLM provider(모델 제공자)를 지원합니다. 상용 모델 제공자뿐 아니라, 직접 운영하는 모델 서버도 연결할 수 있다는 점이 중요합니다.
회사나 팀이 이미 쓰는 API 키가 있다면 Onyx 위에서 연결해 사용할 수 있습니다. 이 경우 모델 운영은 제공자가 맡고, Onyx는 업무 화면과 연결 기능을 맡습니다.
자체 서버나 로컬 환경에서 모델을 돌리는 경우도 염두에 둡니다. 보안·비용·커스터마이징 요구가 큰 팀에게 의미 있는 선택지입니다.
AI 모델은 주방장이고, Onyx는 식당 운영 시스템입니다. 주방장이 OpenAI일 수도, 사내 서버의 오픈소스 모델일 수도 있습니다. Onyx의 역할은 손님 주문을 받고, 필요한 재료를 창고에서 찾고, 결과물을 테이블에 내놓는 흐름을 만드는 것입니다.
팀 AI의 품질은 모델보다 연결된 자료에서 갈릴 때가 많다.
Onyx README는 50개 이상의 indexing 기반 커넥터와 MCP를 언급합니다. 여기서 핵심은 “AI에게 우리 회사 자료를 어떻게 보여줄 것인가”입니다. 아무리 좋은 모델도 사내 문서, 티켓, 위키, 파일 내용을 모르면 일반론만 말하게 됩니다.
연결할 수 있는 곳이 많다는 것은 장점이지만, 동시에 권한·민감정보·동기화 범위를 잘못 잡으면 위험도 커집니다. “많이 연결”보다 “필요한 것만 정확히 연결”이 먼저입니다.
처음에는 공개 가능하거나 민감도가 낮은 자료부터 연결하고, 답변이 어떤 문서를 근거로 삼는지 확인하는 흐름을 만드는 편이 안전합니다.
처음 써볼 때와 실제 운영할 때의 무게가 다르다.
Onyx 문서는 두 가지 배포 모드를 설명합니다. 초보자는 이 구분을 꼭 이해해야 합니다. 같은 Onyx라도 “가볍게 채팅 UI로 써보기”와 “문서 색인·작업자·벡터 검색까지 운영하기”는 필요한 자원이 다릅니다.
문서에 따르면 Lite는 1GB 미만 메모리로도 돌아가는 가벼운 Chat UI에 가깝습니다. Chat, Agents, tools, file uploads, Projects 같은 기능을 빠르게 시험해보려는 사용자에게 맞습니다.
Standard는 전체 기능을 위한 모드입니다. RAG를 위한 벡터+키워드 인덱스, 커넥터 동기화를 위한 백그라운드 컨테이너, 인덱싱과 추론에 쓰는 모델 서버, Redis와 MinIO 같은 성능 구성요소가 포함됩니다.
README는 한 줄 설치와 Docker Compose를 강조한다.
README에는 한 줄 설치 명령이 소개되어 있습니다. 배포 문서에는 Docker, Kubernetes, Helm, Terraform, 주요 클라우드 배포 가이드도 언급됩니다. 즉, 개인 테스트부터 팀 운영까지 넓게 다루려는 구조입니다.
다만 초보자라면 이 명령을 바로 서버에서 실행하기 전에, 공식 문서의 quickstart와 resourcing 안내를 먼저 읽는 편이 좋습니다. 특히 Standard 모드는 여러 컨테이너와 저장소 구성요소가 붙기 때문에 “설치됐다”와 “운영 가능하다”가 다를 수 있습니다.
한 줄 설치는 빠른 시작에는 좋지만, 실제 팀 운영에서는 백업, 업그레이드, 인증, 권한, 로그, 저장소 용량, 모델 비용을 함께 봐야 합니다.
처음에는 Lite나 Cloud Trial로 감을 잡고, 그다음 제한된 데이터로 Standard를 시험한 뒤, 실제 운영 전 보안과 비용을 검토하는 단계가 안전합니다.
무료로 쓸 수 있는 부분과 조직 기능을 구분해서 봐야 한다.
README는 Onyx Community Edition이 MIT 라이선스로 제공되며, Chat, RAG, Agents, Actions의 핵심 기능을 포함한다고 설명합니다. 반면 Enterprise Edition은 큰 조직에 유용한 추가 기능을 담는다고 소개합니다.
개인이나 작은 팀이 Onyx의 기본 가치를 확인하기 좋은 영역입니다. 저장소의 LICENSE는 일부 ee 디렉터리 콘텐츠가 별도 Onyx Enterprise License를 따른다고 구분합니다.
README는 SSO, OIDC, SAML, SCIM, RBAC, 사용량 분석, 쿼리 히스토리, 화이트라벨링 같은 조직 기능을 소개합니다. 큰 회사에서는 AI 성능만큼이나 접근 권한과 감사가 중요하기 때문입니다.
모든 사람에게 필요한 도구는 아니지만, 맞는 상황은 분명하다.
Onyx는 “그냥 혼자 가끔 AI에게 질문하는 사람”보다, 팀 자료를 연결하고 여러 사람이 함께 쓰는 AI 작업 공간이 필요한 경우에 더 의미가 큽니다. 특히 보안이나 자체 배포가 중요한 조직이라면 오픈소스라는 점도 장점입니다.
위키, 문서, 정책, 고객지원 자료가 많아 사람이 매번 찾기 어렵다면 RAG와 내부 검색이 도움이 될 수 있습니다.
상용 모델과 자체 모델을 함께 검토하거나, 장기적으로 특정 제공자에 묶이고 싶지 않은 팀에게 유리합니다.
이 경우에는 Onyx Standard 같은 완전한 플랫폼이 과할 수 있습니다. 관리할 컨테이너, 데이터 연결, 권한 설정이 늘어나기 때문입니다.
Onyx의 역할을 4컷으로 다시 보기.
하지만 우리 팀 문서와 업무 도구를 모르면 일반론만 말하기 쉽다.
채팅 화면에 모델, 문서, 커넥터, 도구를 한곳으로 모은다.
RAG로 근거를 찾고, 에이전트와 액션으로 업무 흐름을 만든다.
연결 자료, 권한, 배포 모드, 비용을 확인해야 안전하게 쓸 수 있다.