oomol-lab/open-connector 딥다이브
— AI 에이전트에게 "열쇠를 주지 않고" 1,000개 SaaS를 열어주는 게이트웨이

1프로젝트 한 줄 요약

"에이전트에게 API 키를 넘기지 말고, 대신 '이 계정으로 이 동작을 실행해 줘'라고 부탁할 창구를 하나 세워라" — 그 창구를 1,000개 서비스 분량으로 미리 만들어 둔 오픈소스 런타임이다.

구체적으로는 네 가지 입구를 제공한다. SDK(앱 코드에서 호출), oo CLI(로컬 에이전트 릴레이), MCP(Claude 같은 에이전트 호스트가 붙는 표준 프로토콜), HTTP/OpenAPI(그 외 모든 클라이언트). 그리고 브라우저에서 쓰는 Web Console이 관리·디버깅용으로 함께 들어 있다.

# 인증이 필요 없는 액션으로 런타임이 살아있는지 확인
curl -s -X POST http://localhost:3000/v1/actions/hackernews.get_top_stories \
  -H 'content-type: application/json' \
  -d '{"input":{}}'

# GitHub 개인 액세스 토큰을 게이트웨이에 "보관"시킨다 (에이전트에겐 안 준다)
curl -s -X PUT http://localhost:3000/api/connections/github \
  -H 'content-type: application/json' \
  -d '{"authType":"api_key","values":{"apiKey":"github_pat_..."}}'

# 이제 에이전트는 토큰 없이 액션 ID만으로 실행한다
curl -s -X POST http://localhost:3000/v1/actions/github.get_current_user \
  -H 'content-type: application/json' \
  -d '{"input":{}}'

2왜 주목받는가

배경 — 2026년 에이전트 개발의 병목은 "연결"이다

LLM 자체는 이제 충분히 똑똑하다. 문제는 에이전트가 실제로 뭔가를 하려면 사용자의 Gmail·Notion·Slack에 접근해야 하는데, 그 인증을 붙이는 일이 지루하고 위험하다는 것이다. 서비스마다 OAuth 흐름이 다르고, 토큰 갱신 주기가 다르고, 스코프 이름이 다르다. 프로바이더 10개만 붙여도 인증 코드가 앱 코드를 잡아먹는다.

Composio 같은 상용 서비스가 이 문제를 대신 풀어주면서 빠르게 성장했다. 그런데 상용 SaaS에 사용자의 모든 앱 자격증명을 위탁하는 구조는 보안·컴플라이언스 관점에서 부담이 크다. "자체 호스팅 가능한 같은 것"에 대한 수요가 자연스럽게 생겼고, OpenConnector가 그 자리를 노린다.

차별점 5가지

3기술 스택 전체 지도

백엔드 (런타임 코어)

프론트엔드 (Web Console)

인프라 · 배포

4아키텍처 심화 분석

전체 구조도

그림에서 가장 중요한 선은 아래쪽 신뢰 경계다. 위쪽(에이전트·앱)은 자격증명을 한 번도 만지지 않는다. 아래쪽(외부 API)으로 나가는 순간에만 SecretCodec이 복호화한 토큰이 헤더에 실린다. 그리고 그 나가는 길목에 guardedFetch가 서 있다.

설계 패턴 ① — 지연 로딩 레지스트리 (프로바이더 1,097개를 살려내는 법)

// src/providers/provider-loader.ts (주석 발췌 — 의도가 명시돼 있다)
/**
 * Loads provider executor modules only when an action is executed.
 *
 * Provider definitions are intentionally not exposed here. Runtime catalog
 * reads should use generated `catalog/apps/*.json` instead of importing
 * hundreds of provider definition modules at startup.
 */
export interface IProviderLoader {
  loadActionExecutor(service, actionId, providerDisplayName?): Promise<ActionExecutor | undefined>;
  loadProxyExecutor(service, providerDisplayName?): Promise<ProviderProxyExecutor | undefined>;
  loadCredentialValidators(service): Promise<CredentialValidators | undefined>;
}

설계 패턴 ② — SSRF 방어선 guardedFetch

이 저장소에서 가장 배울 게 많은 파일이다. 소스 14.5KB, 테스트 18KB — 테스트가 구현보다 크다는 것 자체가 이 코드의 위험도를 말해준다.

왜 이 게이트웨이가 특히 위험한가? URL의 일부가 사용자 입력에서 온다. 프로바이더 중에는 API 베이스 URL을 사용자가 직접 설정하는 것들이 있고(예: clickhouse, dataforseo), 에이전트가 만든 파라미터가 경로에 들어간다. 즉 "LLM이 지어낸 문자열이 서버의 아웃바운드 요청 주소가 될 수 있는" 구조다.

방어 계층 3중

세 번째 계층에서 나오는 디테일이 특히 좋다. 교차 출처(cross-origin) 리다이렉트가 발생하면 인증 헤더를 전부 떼어낸다.

// src/core/guarded-fetch.ts — 명시적 allowlist로 관리한다
const crossOriginCredentialHeaders = new Set([
  "authorization", "proxy-authorization", "cookie",
  "api-key", "apikey", "x-api-key", "x-apikey",
  "api-token", "x-api-token",
  "auth-token", "x-auth-token", "x-auth-key",
  "access-token", "x-access-token", "app-key",
  // ...
]);

설계 패턴 ③ — 액션 정의를 "선언"으로 만드는 팩토리

프로바이더 1,097개를 일관된 모양으로 유지하려면 보일러플레이트를 줄여야 한다. defineProviderAction이 그 역할을 한다.

// src/core/provider-definition.ts
export function defineProviderAction<TName extends string>(
  service: string,
  input: DefineProviderActionInput<TName>,
): ProviderActionDefinition<TName> {
  return {
    id: `${service}.${input.name}`,   // github + get_issue → "github.get_issue"
    service,
    name: input.name,
    description: input.description,
    requiredScopes: input.requiredScopes ?? [],
    providerPermissions: input.providerPermissions ?? [],
    inputSchema: input.inputSchema,
    outputSchema: input.outputSchema,
    followUpActions: input.followUpActions,
    asyncLifecycle: input.asyncLifecycle,
  };
}

주목할 필드가 둘 있다. followUpActions는 "이 액션 다음에 보통 뭘 하게 되는지"를 에이전트에게 힌트로 준다 — 예를 들어 이슈를 만들면 다음은 라벨 붙이기. asyncLifecycle은 오래 걸리는 작업(영상 인코딩 등)의 폴링 계약을 표현한다. 둘 다 "에이전트가 스스로 다음 수를 두게" 돕는 메타데이터다.

프로바이더 정의 자체는 놀랍도록 짧다. GitHub 전체가 이 정도다:

// src/providers/github/definition.ts (전문에 가깝게)
export const provider: ProviderDefinition = {
  service: "github",
  displayName: "GitHub",
  categories: ["Developer Tools"],
  authTypes: ["oauth2", "api_key"],
  auth: [
    { type: "oauth2",
      authorizationUrl: "https://github.com/login/oauth/authorize",
      tokenUrl: "https://github.com/login/oauth/access_token",
      scopes: githubOAuthScopes,
      tokenEndpointAuthMethod: "client_secret_post" },
    { type: "api_key",
      label: "Personal access token",
      placeholder: "github_pat_...",
      description: "...Fine-grained tokens are recommended." },
  ],
  homepageUrl: "https://github.com",
  actions: githubActions,
};

파일 분할 규칙도 일관적이다 — definition.ts(메타), actions.ts(스키마), executors.ts(자격증명 배선), runtime-*.ts(도메인별 실제 호출), scopes.ts(스코프 상수). GitHub은 runtime-issue.ts, runtime-pull-request.ts, runtime-release.ts, runtime-search.ts, runtime-activity.ts, runtime-repository.ts로 도메인을 쪼갰다.

설계 패턴 ④ — 정책 엔진: allow와 block은 서로를 모른다

// src/core/action-policy.ts
evaluate(action: ActionDefinition): ActionPolicyDecision {
  // 1) 차단 목록이 먼저 — 항상 이긴다
  if (this.blocked.some((m) => m(action.id)))
    return { allowed: false, code: "action_blocked", ... };

  // 2) 허용 목록이 비어있지 않으면, 거기 없는 건 전부 거부
  if (this.allowed.length > 0 && !this.allowed.some((m) => m(action.id)))
    return { allowed: false, code: "action_not_allowed", ... };

  return { allowed: true };
}

규칙 세 가지가 명확하다. ①차단이 허용을 이긴다. ②허용 목록이 비어 있으면 "제한 없음"이다(빈 목록 = 전부 거부가 아니다). ③액션 정책과 프록시 정책은 완전히 독립적이다 — 소스 주석이 "Neither pair reads the other"라고 못박아 뒀다.

패턴 매칭은 딱 세 가지만 지원한다 — *(전부), github.*(서비스 단위), 정확히 일치. 정규식을 허용하지 않은 것도 판단이다. 보안 정책 문법이 표현력을 얻으면 그만큼 "의도와 다르게 매칭되는" 사고가 늘어난다.

# docker-compose.yml 환경변수로 바로 설정된다
OOMOL_CONNECT_ALLOWED_ACTIONS=github.*,gmail.get_message
OOMOL_CONNECT_BLOCKED_ACTIONS=github.delete_repository

설계 패턴 ⑤ — 멱등성 키로 "재시도 = 중복 실행"을 막는다

에이전트는 타임아웃이 나면 그냥 다시 시도한다. 그런데 "이슈 생성"이나 "메일 발송"에서 재시도는 중복을 만든다. OpenConnector는 HTTP 표준 방식으로 해결한다:

IDEMPOTENCY_KEY=$(openssl rand -hex 16)

curl -s -X POST http://localhost:3000/v1/actions/github.create_issue \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H 'content-type: application/json' \
  -d '{"input":{"owner":"me","repo":"x","title":"버그"}}'

키가 없으면 매번 정상 실행된다(기본값이 안전한 쪽이 아니라 예측 가능한 쪽이다). 키는 공백 제거 후 비어있지 않아야 하고 255 UTF-8 바이트 이하여야 하며, 위반 시 400 invalid_input. 저장은 migrations/0003_action_idempotency.sql의 전용 테이블에서 담당한다.

보너스 — MCP 툴을 4개로 줄인 결정

5디렉토리 구조 해부

특이한 파일 둘

6학습 포인트

① 보안: 아웃바운드 요청도 입력 검증 대상이다

대부분의 개발자는 들어오는 요청만 검증한다. 이 저장소는 나가는 요청을 검증하는 법을 통째로 보여준다. 배울 항목:

• URL 검사 → DNS 재검증 → 리다이렉트 추적 3단계. 앞 단계만으론 DNS rebinding을 못 막는다.
• 교차 출처 리다이렉트 시 인증 헤더 제거. 이걸 안 하면 evil.com이 302로 리다이렉트해서 당신 서버가 자기한테 API 키를 보내게 만들 수 있다.
• allowlist가 정규식보다 안전하다는 판단 근거를 주석으로 남기기.
• 성능 탈출구를 의도적으로 열어두기 — skipDnsValidation은 "호스트가 코드에 고정된 경우에만 안전하다"는 조건을 주석에 명시한 채 기본 활성화돼 있다. 보안과 성능의 트레이드오프를 숨기지 않고 문서화했다.

실습 아이디어: 당신의 프로젝트에서 사용자 입력이 URL의 일부가 되는 지점을 전부 찾아보라. 웹훅 등록, 이미지 URL 프록시, OAuth 리디렉트 URI — 대부분의 앱에 최소 하나는 있다.

② 아키텍처: "생성물"과 "런타임"을 분리하는 규모 대응

1,097개 프로바이더가 강제한 설계지만, 원리는 훨씬 작은 규모에도 적용된다.

실습 아이디어: 앱 부팅 시간이 느리다면 "부팅에 필요한 것"과 "쓸 때 필요한 것"을 나눠보라. 라우트 핸들러, 관리자 페이지, 리포트 생성기 같은 것들은 대개 후자다.

③ 인터페이스 설계: 이중 런타임을 지탱하는 추상화

같은 코드가 Node와 Workers에서 도는 건 마법이 아니라 인터페이스를 좁게 뽑은 결과다.

// src/server/secrets/secret-codec-core.ts — 인터페이스는 딱 3개 멤버
export interface ISecretCodec {
  readonly encrypted: boolean;
  encode(plaintext: string): Promise<string>;
  decode(stored: string): Promise<string>;
}

// 구현체 3개가 이걸 만족한다:
//  PlainTextSecretCodec  (암호화 키 미설정 시 — 아무것도 안 함)
//  AesGcmSecretCodec     (Node: node:crypto의 scryptSync + aes-256-gcm)
//  WorkerSecretCodec     (Workers: WebCrypto)

같은 패턴이 저장소(runtime-store.ts ← SQLite/D1), 파일 전송(transit-file-store.ts ← R2/KV/로컬)에도 반복된다. "인터페이스는 3~5개 메서드를 넘기지 않는다"는 규율이 이식성을 만든다.

④ 에이전트 인터페이스 설계: 툴을 줄이고 검색을 줘라

MCP나 함수 호출로 도구를 노출하는 모든 개발자에게 해당한다. 정리하면:

• 도구가 20개를 넘어가면 목록 대신 검색을 고려하라.
• 도구별 사용 설명서를 런타임이 생성해서 제공하라(agent.md 패턴).
• followUpActions처럼 "다음에 뭘 할 수 있는지"를 응답에 실어주면 에이전트가 스스로 계획을 세운다.
• 실행 결과를 균일한 봉투({success, message, data, meta})에 담으면 에이전트의 파싱 실패가 줄어든다.

⑤ 운영: 감사 가능성을 처음부터 설계에 넣기

마이그레이션 파일 이름만 봐도 이 프로젝트가 무엇을 중요하게 여겼는지 보인다:

그리고 run-log-summary.ts의 summarizeForRunLog / safeRunLogError — 로그에 남기기 전에 민감값을 마스킹하고 크기를 줄이는 전용 모듈이다. 로깅을 나중에 붙이면 절대 나오지 않는 구조다.

7하드웨어 / 시스템 요구사항

필수 환경변수 정리

# 저장 위치 (Docker는 /app/data 볼륨)
OOMOL_CONNECT_DATA_DIR=/app/data

# ★ 자격증명 암호화 키 — 설정 안 하면 평문 저장된다(PlainTextSecretCodec)
OOMOL_CONNECT_ENCRYPTION_KEY=<충분히 긴 랜덤 문자열>

# 관리 API·콘솔 보호
OOMOL_CONNECT_ADMIN_TOKEN=...
# /v1/*, /mcp 호출자 인증
OOMOL_CONNECT_RUNTIME_TOKEN=...

# OAuth 콜백 주소 계산에 쓰임
OOMOL_CONNECT_ORIGIN=http://localhost:3000

# JWT 검증 (셋을 함께 설정할 때만 활성 · Node 전용)
OOMOL_CONNECT_JWKS_URI=...
OOMOL_CONNECT_JWT_ISSUER=...
OOMOL_CONNECT_JWT_AUDIENCE=...

# 정책
OOMOL_CONNECT_ALLOWED_ACTIONS=...
OOMOL_CONNECT_BLOCKED_ACTIONS=...
OOMOL_CONNECT_ALLOWED_PROXIES=...
OOMOL_CONNECT_BLOCKED_PROXIES=...

8직접 해볼 수 있는 실습 과제

OOMOL_CONNECT_ALLOWED_ACTIONS=github.get_*,github.list_*
OOMOL_CONNECT_BLOCKED_ACTIONS=github.delete_repository

9관련 기술 심화 학습 로드맵

10핵심 키워드 사전

11참고 링크

이 저장소

• oomol-lab/open-connector — 본체 (Apache-2.0)
• docs/quickstart.md — 첫 연결과 OAuth 흐름
• docs/runtime-api.md — 엔드포인트·MCP 툴 전체 레퍼런스
• docs/credentials.md — 자격증명·OAuth 클라이언트 설정
• docs/cloudflare.md — Workers + D1 + R2 배포
• docs/catalog-format.md — 카탈로그 JSON 스키마
• CONTRIBUTING.md · AGENTS.md — 사람용 / 에이전트용 기여 규칙
• 중국어 README — 영문판보다 예시가 더 많을 때가 있다

주변 도구

• oomol-lab/connector-sdk — TypeScript HTTP 클라이언트
• oomol-lab/oo-cli — 로컬 에이전트 릴레이 CLI
• OOMOL — 같은 계약을 쓰는 호스팅 런타임(상용)

기반 기술

• Hono — Web 표준 기반 HTTP 프레임워크
• Model Context Protocol — MCP 공식 명세
• Cloudflare Workers · D1 · R2
• OWASP SSRF Prevention Cheat Sheet — 3장·6장의 배경 지식
• Oxc (oxlint · oxfmt) — Rust 기반 JS/TS 툴체인
• Zod · Vitest · MiniSearch