Oriel이 음성·채팅 웹사이트 도우미를 오픈소스로 공개했다

Oriel은 웹사이트나 앱에 음성·채팅 도우미를 추가할 수 있는 오픈소스 프로젝트다. 방문자는 음성으로 질문하거나 직접 입력할 수 있고, 도우미는 제품 관련 질문에 답하거나 페이지 이동과 결제 정보 변경 같은 작업을 수행할 수 있다.

Oriel 웹사이트에서 호스팅 버전을 이용하거나, 모든 기능을 포함한 버전을 무료로 직접 운영할 수 있다. 코드는 GitHub 저장소에서 확인할 수 있다.

기능과 작동 방식

Oriel은 10개 언어로 음성 대화를 지원하며, 방문자가 말하는 중간에 끼어들 수 있다. 통화 내용은 대화록으로 저장된다. 같은 도우미를 채팅으로도 쓸 수 있으며, 두 방식은 지식과 기능, 기록을 공유한다.

도우미에는 웹사이트와 문서, PDF·Word 파일을 제공할 수 있다. Oriel은 웹페이지를 다시 읽어 답변에 최신 내용이 반영되도록 한다. 방문자가 현재 보고 있는 페이지를 파악해 다른 페이지로 안내하거나 필요한 버튼을 가리킬 수도 있다.

API 호출, 앱의 함수 실행, Stripe 정보 조회·변경 같은 작업도 설정할 수 있다. 어떤 작업에 방문자의 사전 동의가 필요한지는 운영자가 정한다. 서버에서 방문자 정보를 전달하면 도우미가 해당 사용자의 계정만 다루도록 할 수 있다.

팀에는 버그 제보, 기능 요청, 불만, 취소를 고려하는 고객에 관한 내용을 전달한다. 방문자는 담당자의 연락을 요청할 수도 있다. Slack 알림, Zendesk·Salesforce·HubSpot 티켓 생성과 잠재 고객 저장, Cal.com·Calendly 일정 예약도 지원한다. 모델은 Claude, Gemini, GPT 중에서 선택하며, 첫 모델이 실패할 때 사용할 대체 모델도 지정할 수 있다. 팀원을 초대해 워크스페이스를 함께 쓰거나, 에이전시가 고객별 워크스페이스를 만들 수 있다.

설정 절차는 도우미에 웹사이트·문서·파일과 방문자를 안내할 페이지를 제공하고, Stripe나 API·앱 함수를 연결한 뒤, 설치 페이지에서 스크립트를 복사해 사이트에 넣는 방식이다.

<script src="https://useoriel.com/embed.js" data-agent-id="your-assistant-id" async></script>

로그인한 사용자의 계정에서 작업하도록 하려면 서버에서 도우미의 비밀 식별 키를 이용해 JWT 토큰에 서명한 뒤 Oriel("identify", { token })으로 전달해야 한다.

통화에서는 Gemini가 방문자의 음성을 텍스트로 바꾸고, 도우미 모델이 답변을 작성한 뒤 ElevenLabs가 음성으로 출력한다. 개발자는 Next.js, React, Tailwind CSS, Supabase(Postgres와 pgvector, 로그인), Vercel AI SDK를 통해 연결하는 Claude·Gemini·GPT, 음성 처리용 Gemini·ElevenLabs, 그리고 Stripe·Resend·Upstash를 사용해 프로젝트를 구성했다.

직접 설치하기

직접 호스팅하는 버전은 요금제나 사용량 제한 없이 모든 기능을 제공한다. 데이터베이스와 API 키는 직접 준비해야 한다. 로컬 설치에는 Node 22 이상, Docker, Supabase CLI가 필요하다.

npm install
supabase start # starts a local database
cp .env.example .env.local # then add your keys
npm run dev # http://localhost:3010

로컬 환경에서는 로그인 코드가 이메일함이 아니라 http://127.0.0.1:55424의 Mailpit으로 전송된다. 처음 로그인하면 워크스페이스가 생성된다. 도우미를 만든 다음 Playground를 열어 대화할 수 있다. npm run app-assistant를 실행하면 대시보드 안에서 질문에 답하는 도움말 도우미가 추가된다. npm run db:reset은 로컬 데이터를 지우고 데이터베이스를 다시 만든다.

Google 로그인을 쓰는 것은 선택 사항이다. 사용하려면 Google OAuth 클라이언트의 ID와 비밀 키를 .env에 넣어야 하며, .env.local에 넣어서는 안 된다. 리디렉션 URI로 http://127.0.0.1:55421/auth/v1/callback을 추가한 뒤 Supabase를 다시 시작한다.

.env.example에는 각 설정 항목의 설명이 있다. 시작할 때 필요한 설정은 앱 주소인 NEXT_PUBLIC_APP_URL, supabase status에서 확인하는 Supabase URL과 키, 검색·요약·통화 중 음성 이해에 사용하는 Gemini용 GOOGLE_API_KEY, 그리고 무작위 문자열 두 개를 지정하는 WIDGET_SESSION_SECRET과 ENCRYPTION_KEY다. 무작위 문자열은 예를 들어 openssl rand -hex 32로 만들 수 있다. 저장된 키를 읽을 수 없게 되므로 ENCRYPTION_KEY는 나중에 바꾸지 말아야 한다.

필요한 기능에 따라 다음 키를 추가한다.

• 음성 통화에는 ELEVENLABS_API_KEY가 필요하다. 이 키가 없으면 도우미는 텍스트만 지원한다.
• 기본 모델인 Claude Haiku를 쓰려면 ANTHROPIC_API_KEY가 필요하다. 없으면 도우미는 Gemini를 사용한다.
• GPT를 쓰려면 OPENAI_API_KEY를 설정한다.
• 초대와 후속 연락 이메일을 보내려면 RESEND_API_KEY를 설정한다.

NEXT_PUBLIC_EDITION은 설정하지 않은 상태로 둔다. 이 값을 cloud로 설정하면 useoriel.com에서 사용하는 요금제·결제 기능과 마케팅 사이트가 활성화된다.

배포와 연동 서비스

Oriel은 일반적인 Next.js 앱이다. 프로젝트 운영자는 호스팅된 Supabase 프로젝트와 함께 Vercel에서 운영한다. 빌드 전에 NEXT_PUBLIC_APP_URL을 설정해야 하며, 이 값은 임베드 스크립트에 기록된다. Supabase 프로젝트에는 supabase/migrations의 마이그레이션을 적용해야 한다. 예를 들어 supabase db push를 사용할 수 있다. CRON_SECRET도 설정해야 한다. vercel.json의 예약 작업은 이 값을 사용해 매일 지식 자료를 갱신한다. 로그인 코드는 Supabase가 보내므로 Supabase 프로젝트에서 이메일(SMTP)을 설정해야 한다.

각 도우미는 Integrations 페이지에서 서비스를 연결한다. 연동 서비스와 역할은 다음과 같다.

서비스는 OAuth, 키 또는 두 방식을 함께 이용해 연결한다. OAuth를 쓸 때는 <NEXT_PUBLIC_APP_URL>/api/integrations/<service>/callback을 리디렉션 URL로 등록한다. 필요한 키가 없으면 대시보드의 해당 서비스 카드에 표시된다.

Stripe 고객은 제한된 키를 붙여 넣거나 Oriel의 Stripe 앱을 설치할 수 있다. 앱을 공개하려면 stripe apps upload integrations/stripe-app --live로 실제 Stripe 계정에 업로드하고, 설치 링크를 STRIPE_APP_INSTALL_URL에 설정한다. 다른 계정에서 설치하려면 Stripe의 검토를 통과해야 한다.

Slack 연동에는 integrations/slack-app-manifest.yml을 이용해 앱을 만든 뒤 SLACK_CLIENT_ID와 SLACK_CLIENT_SECRET을 설정한다. Slack은 HTTPS 리디렉션 URL만 허용하므로 로컬에서는 NEXT_PUBLIC_APP_URL=https://localhost:3010과 함께 npm run dev:https를 실행한다. 다른 Slack 워크스페이스에서도 설치할 수 있도록 공개 배포를 켜야 한다.

Zendesk는 별도의 사전 설정이 필요하지 않다. 각 고객이 자신의 Zendesk에서 OAuth 클라이언트를 만들며, 대시보드가 설정 과정을 안내한다. Salesforce도 고객이 직접 앱을 만들고 대시보드의 안내를 따른다. 원클릭 연결 버튼을 제공하려면 자체 앱을 패키징해 SALESFORCE_CLIENT_ID와 SALESFORCE_CLIENT_SECRET을 설정한다.

HubSpot은 고객이 서비스 키를 붙여 넣어 연결할 수 있다. 연결 버튼을 제공하려면 HubSpot 앱을 만들고 HUBSPOT_CLIENT_ID와 HUBSPOT_CLIENT_SECRET을 설정한다. 앱이 HubSpot 마켓플레이스에 등록되기 전에는 최대 25개 계정에서 작동한다.

Cal.com은 자체 호스팅 버전에서도 쓸 수 있는 API 키를 고객이 붙여 넣어 연결할 수 있다. 연결 버튼을 만들려면 PROFILE_READ, EVENT_TYPE_READ, BOOKING_READ, BOOKING_WRITE 범위가 있는 OAuth 클라이언트를 만들고 CALCOM_CLIENT_ID와 CALCOM_CLIENT_SECRET을 설정한다.

Calendly는 고객이 개인 액세스 토큰을 붙여 넣어 연결할 수 있다. 연결 버튼을 제공하려면 users:read, event_types:read, scheduled_events:write 범위가 있는 OAuth 앱을 만들고 CALENDLY_CLIENT_ID와 CALENDLY_CLIENT_SECRET을 설정한다. 예약 기능에는 유료 Calendly 요금제가 필요하다. 무료 요금제에서는 도우미가 방문자 정보를 채운 예약 링크를 보낸다.

기여와 라이선스

기여를 위한 풀 리퀘스트를 받는다. 먼저 CONTRIBUTING.md를 읽어야 한다. 첫 풀 리퀘스트를 제출할 때는 CLA에 한 번 서명해야 한다. 보안 문제는 공개하지 말고 비공개로 제보해야 하며, 자세한 방법은 SECURITY.md에 안내돼 있다.

Oriel은 호스팅 서비스의 결제 기능과 마케팅 사이트를 포함해 AGPL-3.0 라이선스로 공개됐다. 변경한 Oriel을 다른 사람에게 서비스로 제공하는 경우에는 그 사용자에게 소스 코드를 공유해야 한다. 이 조건이 적용되지 않는 상업용 라이선스는 hello@useoriel.com으로 문의할 수 있다. Oriel의 이름과 로고는 라이선스에 포함되지 않으며, 자세한 내용은 TRADEMARKS.md에 있다.

부록: 원문 예시

. Slack only accepts https redirect URLs, so locally run