OpenConnector: 에이전트에 자격 증명을 넘기지 않고 1,000여 개 SaaS에 연결하는 오픈소스 게이트웨이

9bow · 8월 25, 2026, 1:30오전

OpenConnector 소개

AI 에이전트에게 메일을 읽히거나 협업 도구에 글을 남기게 하려면 그 계정에 접근할 권한이 필요합니다. 가장 빠른 방법은 API 키와 OAuth 토큰을 에이전트 프로세스의 환경 변수에 넣어 두는 것인데, 이렇게 하면 에이전트가 잘못 판단하거나 프롬프트 주입(Prompt Injection)에 당했을 때 피해 범위가 그 계정 전체로 번집니다. 연결할 서비스가 늘어나면 부담은 인증 하나로 끝나지 않습니다. 서비스마다 인증 방식과 토큰 갱신 주기, 요구하는 권한 범위(Scope)가 달라서 연동 코드가 에이전트 안에 하나씩 쌓이고, 어느 순간 그 코드를 관리하는 일이 원래 만들려던 에이전트보다 커집니다.

이번에 소개할 OpenConnector는 그 연결을 에이전트 바깥의 별도 게이트웨이(Gateway)로 옮긴 프로젝트입니다. 사용자가 앱 계정을 한 번 연결해 두면 게이트웨이가 자격 증명(Credential)을 자기 경계 안에 보관하고, 에이전트에게는 실행할 수 있는 작업(Action) 목록과 그 실행 결과만 넘깁니다. 프로젝트는 이 구조를 두고 "Provider secrets stay behind the runtime boundary"라고 설명하면서, 에이전트가 받는 것은 스키마와 안전한 계정 라벨, 실행 결과뿐이라고 밝히고 있습니다. 에이전트 코드에서 사라지는 것은 키만이 아닙니다. 어떤 권한이 필요한지, 토큰이 만료되면 어떻게 갱신하는지, 어떤 작업을 허용할지도 모두 게이트웨이 쪽 설정으로 옮겨갑니다.

OpenConnector를 만든 곳은 OOMOL이고, 저장소는 oomol-lab/open-connector에 TypeScript로 공개되어 있습니다. 실행에는 Node.js 22 이상이 필요하며, 같은 런타임(Runtime)이 Cloudflare Workers 위에서도 동작합니다. 프로젝트가 함께 배포하는 카탈로그에는 GitHub, Gmail, Notion, BigQuery, Google Analytics, Supabase, Airtable, Slack을 비롯한 1,000개 이상의 프로바이더와 10,000개 이상의 미리 만들어 둔 Action이 들어 있습니다. 프로젝트는 스스로를 Pipedream과 Composio의 대안으로 소개합니다. 두 곳 모두 관리형으로 제공되는 통합 서비스이고, OpenConnector는 같은 성격의 카탈로그와 실행 계약을 오픈소스로 공개해 사용자가 직접 운영하도록 합니다.

OpenConnector가 자격 증명을 경계 안에 두는 방법

OpenConnector에서 에이전트와 실제 서비스 사이에 놓이는 것은 런타임 하나입니다. 에이전트는 연결 별칭(Connection Alias)을 골라 Action을 실행하고, 런타임이 그 별칭에 묶인 자격 증명을 꺼내 실제 프로바이더를 호출한 뒤 결과만 돌려줍니다. 지원하는 인증 방식은 API 키, OAuth2, 프로바이더별 커스텀 자격 증명, 그리고 인증이 아예 필요 없는 프로바이더까지 네 가지입니다. 인증만 대신 처리하는 것이 아니라 실행 자체에도 통제 지점을 두는데, 프로젝트가 밝히는 런타임 통제 항목은 연결 식별자, 권한 범위, 런타임 토큰, Action 허용과 차단 정책, 임시 파일 전송 구간, 그리고 민감한 값을 가린 실행 로그입니다.

Action 계약을 열어 볼 수 있게 해 둔 점도 같은 맥락에 있습니다. 각 Action은 요청과 응답 스키마, 필요한 권한 범위를 함께 노출하고 실행기(Executor) 소스는 필요할 때 불러오도록 되어 있어서, 에이전트에 도구를 연결하기 전에 그 도구가 무엇을 요구하고 무엇을 돌려주는지 사람이 먼저 확인할 수 있습니다. 에이전트가 도구를 잘못 쓰는 사고는 대개 계약을 모른 채 호출할 때 생기므로, 스키마와 권한 범위를 검사 가능한 형태로 두는 것은 보안 장치이면서 디버깅 장치이기도 합니다.

로컬에서 실행되는 웹 콘솔은 이 설정을 눈으로 다루는 자리입니다. 프로바이더를 검색하고, API 키와 OAuth 클라이언트를 등록하고, 런타임 토큰을 만들고, Action 스키마를 확인하고, 실제로 한 번 실행해 보고, 최근 실행 기록을 되짚는 일이 한 화면에서 끝납니다. 배포 직후 상태를 확인하는 Overview 페이지에서는 런타임 준비 상태와 사용 가능한 프로바이더 수, 실행 가능한 Action 수, 최근 실패 건수, 도구 호출 추이를 함께 보여줍니다.

OpenConnector에 접근하는 네 가지 경로

같은 런타임에 연결하는 방법은 쓰는 쪽의 형태에 따라 네 가지로 나뉩니다:

경로	쓰는 자리	형태
Connector SDK	애플리케이션 코드 안에서 직접 호출할 때	얇은 TypeScript HTTP 클라이언트
oo CLI	로컬 에이전트가 중계기로 쓸 때	`oo connector` 명령으로 Action 검색, 확인, 실행
MCP ( [Deep Research] Model Context Protocol(MCP) 개념 및 이해를 위한 학습 자료)	MCP를 지원하는 에이전트 호스트에 연결할 때	`http://localhost:3000/mcp` 엔드포인트
HTTP / OpenAPI	위 셋에 해당하지 않는 클라이언트	`/v1/actions/*` 직접 호출, `/openapi.json` 문서

이 가운데 MCP 경로가 특히 실용적인데, 에이전트 호스트 쪽 코드를 고치지 않고도 카탈로그의 Action을 도구로 노출할 수 있기 때문입니다. 반대로 Action을 프로그램 흐름 안에서 조건에 따라 골라 쓰고 싶다면 SDK 쪽이 적절합니다. 엔드포인트 규격과 응답 봉투, 인증 헤더, MCP 도구 목록은 저장소의 docs/runtime-api.md에 정리되어 있습니다.

OpenConnector 설치와 첫 호출

자체 호스팅 런타임은 Docker Compose로 한 줄에 시작합니다. 이 명령은 GitHub Packages에 올라와 있는 ghcr.io/oomol-lab/open-connector:latest 이미지를 받아 실행합니다:

docker compose up

런타임이 실행되면 웹 콘솔은 http://localhost:3000, 자동 생성된 API 참조 문서는 http://localhost:3000/docs에서 열립니다. 인증이 필요 없는 Action을 하나 호출해 보면 런타임이 정상 동작하는지 바로 확인할 수 있습니다:

curl -s -X POST http://localhost:3000/v1/actions/hackernews.get_top_stories \
  -H 'content-type: application/json' \
  -d '{"input":{}}'

자격 증명이 필요한 프로바이더 중에서는 GitHub이 개인 접근 토큰(Personal Access Token) 하나로 끝나 가장 단순합니다. 연결을 등록하고 그 연결로 Action을 실행하는 두 단계는 다음과 같습니다:

curl -s -X PUT http://localhost:3000/api/connections/github \
  -H 'content-type: application/json' \
  -d '{"authType":"api_key","values":{"apiKey":"github_pat_..."}}'

curl -s -X POST http://localhost:3000/v1/actions/github.get_current_user \
  -H 'content-type: application/json' \
  -d '{"input":{}}'

다만 OAuth2를 쓰는 프로바이더는 사정이 다릅니다. 자체 호스팅 런타임에서 OAuth 프로바이더를 쓰려면 그 서비스에 직접 앱을 등록해 OAuth 클라이언트 자격 증명을 받아야 하고, 이 준비를 건너뛰고 싶으면 OOMOL이 운영하는 관리형 커넥터를 쓰라고 프로젝트가 안내하고 있습니다. 명명된 연결과 자격 증명 암호화, 토큰 갱신, Action 정책은 docs/credentials.md와 docs/configuration.md에 나뉘어 있습니다.

OpenConnector를 올릴 수 있는 곳

같은 프로바이더 식별자와 Action 식별자, 같은 스키마와 계약을 유지한 채 실행 환경만 바꿀 수 있다는 것이 OpenConnector가 내세우는 설계 목표입니다. 프로젝트가 제시하는 다섯 가지 경로는 다음과 같습니다:

경로	적합한 팀	구성
자체 호스팅	전체를 직접 통제하려는 개발자와 팀	로컬 Docker 또는 Node 런타임, SQLite 또는 PostgreSQL 상태 저장, 로컬 또는 S3 호환 전송 파일
Kubernetes(Helm)	자체 클러스터를 운영하는 팀	PersistentVolumeClaim 기반 SQLite 또는 PostgreSQL, 마이그레이션 훅, Ingress, 오토스케일링, NetworkPolicy 토글
Fly.io	호스팅형 Docker 런타임을 원하는 팀	Node Docker 런타임, Fly 볼륨의 SQLite 또는 외부 PostgreSQL, TLS, 헬스 체크
Cloudflare 호환 배포	가벼운 호스팅 런타임을 원하는 팀	Workers 런타임, D1 상태 저장, R2 전송 파일, Static Assets 콘솔
OOMOL	사용자가 즉시 계정을 인증하게 하려는 팀	OOMOL이 제공하는 OAuth 앱, 월 단위 포함 크레딧, 호스팅 런타임

한편 Node 런타임은 기본적으로 SQLite를 쓰고, OOMOL_CONNECT_DATABASE_URL을 설정하면 PostgreSQL 15 이상을 씁니다. PostgreSQL 마이그레이션은 명시적이라 보류 중인 변경이 있는 버전을 올리기 전에 npm run runtime:migrate를 먼저 실행해야 하고, 서버는 시작할 때 스키마 준비 상태만 확인할 뿐 DDL을 자동으로 적용하지 않습니다. 운영 환경에서 스키마 변경이 조용히 일어나는 것을 막는 선택이므로, 배포 스크립트에 마이그레이션 단계를 따로 넣어 두어야 합니다.

OpenConnector는 누구에게 맞는가

여러 사용자의 SaaS 계정을 대신 다루는 에이전트 제품을 만들고 있고 자격 증명을 자기 인프라 안에 두어야 하는 팀에게 OpenConnector가 가장 잘 맞습니다. 관리형 서비스에 계정 연결을 맡기면 빠르게 출시할 수 있지만 자격 증명과 실행 로그가 외부에 남고, 직접 만들면 프로바이더마다 인증 코드를 쌓아야 합니다. OpenConnector는 카탈로그와 Action 계약을 그대로 가져가면서 실행 주체만 자기 쪽으로 당겨 오는 중간 선택지입니다. 관리형 런타임으로 먼저 시작한 뒤 나중에 자체 호스팅으로 옮기는 경로를 프로젝트가 계약 호환성으로 열어 둔 것도 같은 이유입니다.

반대로 연결할 서비스가 한두 개로 고정되어 있는 팀에게는 OpenConnector가 과한 선택입니다. 게이트웨이를 하나 더 운영한다는 것은 데이터베이스와 전송 파일 저장소, OAuth 앱 등록, 마이그레이션 절차를 함께 떠안는다는 뜻이고, 프로바이더가 둘뿐이라면 그 비용이 직접 연동보다 큽니다. 에이전트와 서비스를 잇는 문제를 다루는 프로젝트는 이곳 말고도 있으므로, Nango ( Nango: AI 에이전트와 제품을 800여 개 API에 연결하는 통합 플랫폼)처럼 결이 비슷한 프로젝트와 나란히 놓고 카탈로그에 필요한 서비스가 실제로 들어 있는지부터 확인하는 편이 낫습니다.

OpenConnector로 만든 데스크톱 에이전트, Wanta

OpenConnector가 도구 연결을 담당한다면, 그 위에 올라가는 애플리케이션의 예시로 같은 조직이 Wanta를 함께 공개해 두었습니다. Wanta는 OpenCode 기반의 데스크톱 에이전트 애플리케이션이고, 연결된 SaaS 서비스를 다룰 때 OpenConnector를 씁니다. 계정을 만들지 않고 OpenAI 호환 모델을 직접 지정해 로컬에서 돌릴 수 있으며, 포크해서 프롬프트와 도구, 인터페이스, 모델, 브랜딩을 바꾸는 것도 가능합니다. 관리형 모델과 OAuth 연결, 팀 워크스페이스가 필요하면 별도로 운영되는 Wanta 호스팅 서비스를 선택할 수 있습니다.

OpenConnector의 라이선스

OpenConnector는 Apache License 2.0으로 공개되어 있어 개인 및 상업적 목적으로 자유롭게 사용할 수 있습니다.

단, 카탈로그에 이름과 메타데이터, 아이콘이 실려 있는 서드파티 제품과 API, 상표는 이 라이선스의 적용을 받지 않고 각 권리자에게 그대로 남아 있습니다. 카탈로그 등재가 해당 서비스의 보증이나 제휴를 뜻하지 않는다는 점도 프로젝트가 명시하고 있으므로, 프로바이더 자산을 재배포하는 형태로 활용할 계획이라면 그 서비스의 약관을 따로 확인해야 합니다.

OOMOL 홈페이지 (OpenConnector 기반의 관리형 커넥터 서비스)

OpenConnector 자체 호스팅 문서

Cloudflare Workers에 OpenConnector 배포하기

OpenConnector 프로젝트 GitHub 저장소

더 읽어보기

이 글은 GPT 모델로 정리한 초안을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 댓글로 알려주시기를 부탁드립니다.

이 도구를 직접 설치해 사용해보셨다면, 파이토치 한국 사용자 모임 회원들을 위해 경험이나 팁을 댓글로 남겨주세요!