가이드

작성자 Matt Connor 2026-08-01 · 업데이트됨 2026-10-19

Open Connector 직접 호스팅 및 인증 게이트웨이 구축 방법

Q: Open Connector를 셀프 호스팅하려면 공인 도메인이 필요한가요?

API 키를 사용하는 제공자의 경우, 127.0.0.1의 게이트웨이만으로도 충분하므로 필요하지 않습니다. 하지만 OAuth를 사용한다면 실질적으로 필요합니다. 제공자가 브라우저를 콜백 URL로 리다이렉트하므로 해당 URL은 공인 인터넷에서 해석 가능해야 하며, 제공자들은 localhost를 제외한 일반 http:// 연결을 거부하기 때문입니다. 첫 실행 전에 OOMOL_CONNECT_ORIGIN를 본인의 https:// 호스트네임으로 설정하고, 제공자의 OAuth 앱에 /oauth/callback를 등록하십시오.

Q: AI 에이전트가 제공자 액세스 토큰을 볼 수 있나요?

게이트웨이를 통해 호출하는 경우에는 볼 수 없습니다. 에이전트는 oct_로 시작하는 런타임 토큰으로 인증하며, 게이트웨이가 서버 측에서 아웃바운드 요청에 제공자 자격 증명을 주입한 뒤 응답만 반환하기 때문입니다. 이 보안 원칙이 깨지는 경우는 두 가지입니다. 자격 증명이 포함된 원시 요청을 전달하는 /v1/proxy/:service 엔드포인트(이 엔드포인트의 권한이 기본적으로 비어 있는 이유입니다)와, 게이트웨이를 완전히 우회하여 API 키를 에이전트에 직접 붙여넣는 경우입니다.

Q: 게이트웨이를 공인 인터넷에서 접근 가능하게 해야 하나요?

/oauth/callback만 접근 가능하면 됩니다. 컨테이너 포트를 127.0.0.1에 게시하여 Docker의 NAT 규칙이 방화벽 너머로 포트를 노출하지 않도록 하고, 앞단에 리버스 프록시를 배치하십시오. 그 후 authorization 헤더 없이 액션 호출을 하나 테스트해 보십시오. 성공한다면, 인증된 호출만 작동할 때까지 프록시에서 /api, /v1, /mcp를 에이전트가 사용하는 주소로 제한하십시오.

Open Connector를 VPS에 직접 호스팅하여 AI 에이전트가 SaaS 토큰을 직접 보유하지 않도록 보안을 강화합니다. OAuth 콜백 설정부터 TLS 오리진 구성, SQLite 데이터 백업까지 단일 컨테이너 환경에서 안전하게 인증 게이트웨이를 운영하는 실무 가이드를 제공합니다.

Open Connector가 AI 에이전트에서 수행하는 역할

Open Connector를 직접 호스팅하면 AI 에이전트와 에이전트가 호출하는 모든 SaaS(Software as a Service) API 사이에 인증 게이트웨이가 하나 배치됩니다. 따라서 에이전트는 공급자 토큰을 직접 보유하지 않습니다. 이 게이트웨이는 OOMOL Lab에서 제공하는 오픈 소스 소프트웨어이며 Apache 2.0 라이선스를 따릅니다. 단일 컨테이너로 실행되고 단일 SQLite 파일에 상태를 저장하며, HTTP 및 MCP(Model Context Protocol)를 통해 공급자 작업을 노출합니다.

문제는 두 번째 통합부터 시작됩니다. 모든 공급자는 각자의 OAuth(Open Authorization) 흐름, 리프레시 토큰 수명, 스코프 명칭을 가지고 있습니다. 5개의 공급자를 에이전트에 수동으로 연결하려면 5개의 리다이렉트 핸들러, 5개의 자격 증명 저장소, 그리고 토큰 만료 전에 실행되어야 하는 5개의 리프레시 루프가 필요합니다. 이 코드를 직접 작성하는 사람은 거의 없습니다. 대부분 서비스당 하나의 장기 지속형 개인 액세스 토큰을 생성하여 에이전트 설정, 환경 파일 또는 프롬프트 자체에 붙여넣습니다. 그러면 해당 토큰은 에이전트가 실행하는 모든 도구에서 읽을 수 있게 되며, AI 에이전트에서 비밀 정보를 보호하는 방법에서 설명하는 실패 사례처럼 대화 기록에 남게 됩니다.

인증 게이트웨이는 자격 증명을 둘로 분리합니다. 게이트웨이는 공급자 자격 증명을 저장하고 OAuth 흐름을 실행합니다. 에이전트는 게이트웨이에 대해서만 유효한 런타임 토큰을 받습니다. 에이전트가 작업을 호출하면 게이트웨이는 저장된 자격 증명을 불러와 서버 측에서 아웃바운드 요청에 주입하고 응답 본문만 반환합니다. 에이전트는 공급자 액세스 토큰을 직접 받지 않으므로, 에이전트 대화 기록이 유출되더라도 GitHub 계정 전체가 아닌 취소 가능한 런타임 토큰 하나만 노출될 뿐입니다.

카탈로그는 1,000개 이상의 공급자와 10,000개 이상의 사전 구축된 작업을 광고하는데, 이는 프로젝트 자체 수치이며 외부에서 검증할 수 있는 내용은 아닙니다. 검증 가능한 것은 구조입니다. 작업당 하나의 HTTP 엔드포인트, 공급자당 하나의 저장된 연결, 에이전트당 하나의 토큰이 그것입니다. 에이전트 측 기술이 아직 초기 단계이고 도구 호출(tool call)이나 MCP 서버 같은 용어가 정립되지 않았다면, AI 에이전트를 처음부터 배우는 방법에 제시된 단계별 경로를 통해 이와 같은 게이트웨이가 전제로 하는 루프, 도구, 보안 습관을 먼저 익히는 것이 좋습니다.

호스팅된 커넥터 서비스 대신 Open Connector를 직접 호스팅해야 하는 이유

호스팅된 커넥터 서비스도 동일한 작업을 수행하며, 연결된 모든 제공업체의 리프레시 토큰을 보관합니다. Google이나 GitHub의 리프레시 토큰은 사용자의 메일과 저장소에 접근할 수 있는 장기 유효 키이며, 일반적으로 비밀번호를 변경해도 유지됩니다. 해당 서비스가 침해되면 곧 사용자의 침해로 이어집니다. 직접 호스팅을 하면 이러한 기록을 사용자가 임대하고 관리하는 서버의 SQLite 데이터베이스로 옮기게 되며, 서버 외부로 절대 유출되지 않는 키로 보호됩니다.

시작하기 전에 비용을 명확히 인지하십시오. 이 VPS는 운영 중인 서버 중 가장 중요한 서버가 됩니다. 이 서버는 12개 정도의 서비스에 대한 유효한 자격 증명을 하나의 파일에 보관하므로, 비밀번호 관리자 호스트에 준하는 관리가 필요합니다. 443 포트만 개방하는 방화벽을 설정하고, 공유 로그인을 금지하며, 실제로 복구 테스트를 거친 백업을 유지하고, 응답이 없을 경우 알림을 받도록 구성하십시오. 비밀번호 저장소를 이 서버에 두지 않을 것이라면, 커넥터 역시 설치하지 마십시오.

설치 전 버전 고정하기

Open Connector는 초기 단계의 프로젝트입니다. 이 저장소는 2026년 6월 29일에 처음 공개되었으며, 2026년 8월 1일 기준으로 가장 최신 태그가 지정된 릴리스는 2026년 7월 30일에 게시된 v1.3.3입니다. 이 릴리스는 latest 태그도 함께 포함하고 있습니다. 레지스트리에는 main의 최신 커밋에서 빌드된 tip 태그도 게시되어 있습니다.

이처럼 새로운 프로젝트에서는 유동적인 태그가 자주 변경됩니다. 두 번의 릴리스를 건너뛰는 docker compose pull는 에이전트가 의존하는 엔드포인트를 변경할 수 있으며, 이 경우 에이전트 문제로 오인하여 디버깅에 많은 시간을 허비하게 됩니다. 이미지를 특정 릴리스 태그로 고정하고, 릴리스 노트를 확인한 후 직접 결정하여 업그레이드하십시오.

자체 VPS에서 TLS 뒤에 Open Connector 배포하기

컨테이너를 시작하기 전에 다음 항목이 필요합니다.

Ubuntu 24.04 또는 유사한 환경의 Docker 및 Compose 플러그인
A 레코드가 해당 VPS를 가리키는 호스트 이름(예: connect.example.com)
해당 호스트 이름에 대해 이미 TLS(전송 계층 보안)를 종료하는 리버스 프록시
아래에서 생성할 두 개의 임의 비밀값

여러 Docker Compose 앱을 위한 Traefik 리버스 프록시 가이드에서 프록시 설정을 다룹니다. 단일 앱에 대한 전체 인증서 구성 과정은 Docker와 HTTPS를 사용하는 VPS의 n8n 가이드에 있습니다.

먼저 비밀값을 생성합니다. 암호화 키는 저장된 자격 증명을 보호합니다. 관리자 토큰은 웹 콘솔과 /api 전체 인터페이스를 보호합니다. 기본값은 없으며, 값이 없어도 런타임은 정상적으로 시작됩니다.

mkdir -p ~/open-connector && cd ~/open-connector
umask 077
printf 'OOMOL_CONNECT_ENCRYPTION_KEY=%s\n' "$(openssl rand -base64 32)" > .env
printf 'OOMOL_CONNECT_ADMIN_TOKEN=%s\n' "$(openssl rand -base64 32)" >> .env
chmod 600 .env

첫 시작 전에 두 값을 지금 바로 비밀번호 관리자에 복사해 두십시오. 암호화 키는 복구할 방법이 없으며, 그 이유는 아래 실패 목록에 설명되어 있습니다.

이제 compose.yaml을 작성합니다. 이는 업스트림 예제와 두 가지 면에서 다르며, 두 가지 모두 중요합니다.

services:
  connector:
    image: ghcr.io/oomol-lab/open-connector:v1.3.3
    restart: unless-stopped
    ports:
      - "127.0.0.1:3000:3000"
    volumes:
      - connector-data:/app/data
    environment:
      OOMOL_CONNECT_DATA_DIR: /app/data
      OOMOL_CONNECT_ORIGIN: "https://connect.example.com"
      OOMOL_CONNECT_ENCRYPTION_KEY: "${OOMOL_CONNECT_ENCRYPTION_KEY:?set this in .env}"
      OOMOL_CONNECT_ADMIN_TOKEN: "${OOMOL_CONNECT_ADMIN_TOKEN:?set this in .env}"

volumes:
  connector-data:

첫 번째 변경 사항은 latest 대신 고정된 태그를 사용하는 것입니다. 두 번째는 포트입니다. 업스트림 파일은 3000:3000를 게시하여 호스트의 모든 인터페이스에 바인딩합니다. Docker는 ufw 필터 체인이 패킷을 확인하기 전에 게시된 포트를 NAT(네트워크 주소 변환) 테이블에 기록하므로, ufw deny 3000으로는 해당 포트를 차단할 수 없습니다. 이는 Docker 포트가 ufw를 우회하는 이유에서 설명한 함정입니다. 127.0.0.1:3000:3000을 작성하면 루프백 인터페이스에만 게시되며, 리버스 프록시는 동일한 호스트에서 연결을 시도합니다.

:?는 각 변수를 필수 항목으로 표시하므로, .env이 누락되면 자격 증명이 암호화되지 않은 상태로 시작되는 대신 스택이 시작을 거부합니다. Compose 파일 대신 .env에 값을 보관하는 것은 Docker Compose 환경 파일 및 비밀에서 권장하는 패턴입니다.

docker compose up -d
docker compose logs -n 30 connector
curl -s http://127.0.0.1:3000/health
sudo ss -tlnp | grep 3000

런타임이 실행되면 /health가 { "ok": true }에 응답합니다. ss은 반드시 127.0.0.1:3000을 출력해야 합니다. 0.0.0.0:3000라는 줄이 보인다면 포트 매핑이 여전히 업스트림 설정 상태이며, 게이트웨이가 인터넷 전체에 직접 응답하고 있다는 의미입니다. 상태 확인에서 연결이 거부된다면 컨테이너가 아직 수신 대기 중이 아니라는 뜻이므로, 프록시를 수정하기 전에 로그를 먼저 확인하십시오.

동일 서비스를 위한 Traefik 레이블

    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.connector.rule=Host(`connect.example.com`)"
      - "traefik.http.routers.connector.entrypoints=websecure"
      - "traefik.http.routers.connector.tls.certresolver=le"
      - "traefik.http.services.connector.loadbalancer.server.port=3000"

Traefik이 동일한 호스트의 Docker에서 실행 중인 경우, 이 서비스를 Traefik 네트워크에 연결하고 ports: 블록을 삭제하십시오. Traefik이 내부 네트워크를 통해 컨테이너에 접근하므로 호스트에 포트를 게시할 필요가 전혀 없기 때문입니다. certresolver=le은 Traefik 정적 설정의 리졸버 이름과 일치해야 하며, 그렇지 않으면 라우터가 인증서 없이 생성됩니다.

OAuth가 실제 호스트 이름을 요구하는 이유

OOMOL_CONNECT_ORIGIN는 사용자가 자주 생략하는 설정이며, 이를 생략하면 OAuth 제공자의 버그처럼 보이는 오류가 발생합니다. 런타임은 해당 origin을 기반으로 <origin>/oauth/callback 형식의 리다이렉트 URI를 생성합니다. 이 값을 설정하지 않으면 origin은 기본값인 http://localhost:3000로 지정됩니다. 결과적으로 런타임은 http://localhost:3000/oauth/callback라는 리다이렉트 URI를 제공자에게 전송하지만, OAuth 앱에는 https://connect.example.com/oauth/callback이 등록되어 있습니다. 두 문자열이 일치하지 않으므로 GitHub는 다음과 같이 응답합니다.

The redirect_uri MUST match the registered callback URL for this application.

OAuth 제공자는 브라우저를 해당 URI로 리다이렉트하므로, 이 주소는 외부에서 접근 가능해야 합니다. 또한 제공자는 localhost를 제외한 모든 경우에 일반 http:// 주소를 거부합니다. 이것이 바로 이 배포 환경에 호스트 이름과 인증서가 필요한 이유입니다. 이 값은 시작 시점에 읽히므로, 첫 실행 전에 origin을 설정하십시오. .env 또는 compose.yaml를 수정한 후에는 docker compose up -d을 다시 실행하여 설정을 적용해야 합니다.

OAuth를 통해 첫 번째 공급자 연결하기

먼저 공급자 측에서 OAuth 앱을 생성합니다. GitHub의 경우 Settings, Developer settings, OAuth Apps, New OAuth App 순서로 이동합니다. 인증 콜백 URL을 https://connect.example.com/oauth/callback로 설정합니다. 클라이언트 ID와 클라이언트 시크릿을 보관해 둡니다.

모든 /api 호출은 관리자 토큰을 포함하므로, 셸 세션에서 한 번만 export합니다.

export ADMIN_TOKEN='paste-the-admin-token'
curl -s https://connect.example.com/api/oauth/configs \
  -H "authorization: Bearer $ADMIN_TOKEN"

위 목록은 런타임이 각 공급자에 대해 기대하는 리다이렉트 URI를 보여줍니다. 이는 설정이 제대로 적용되었는지 확인하는 가장 빠른 방법입니다. 여전히 localhost으로 표시된다면 컨테이너가 이전 값으로 실행 중인 것이며, OAuth 흐름은 마지막 단계에서 실패하게 됩니다.

클라이언트 자격 증명을 저장한 뒤 인증을 시작합니다.

curl -s -X PUT https://connect.example.com/api/oauth/configs/github \
  -H "authorization: Bearer $ADMIN_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"clientId":"...","clientSecret":"..."}'

curl -s -X POST https://connect.example.com/api/oauth/authorizations \
  -H "authorization: Bearer $ADMIN_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"service":"github"}'

두 번째 호출은 authorizationUrl를 반환합니다. 이를 브라우저에서 열고 스코프를 승인하면, 공급자가 브라우저를 /oauth/callback로 다시 보냅니다. 여기서 런타임은 코드를 교환하고 자격 증명을 저장합니다. 오리진의 웹 콘솔은 동일한 관리자 토큰을 사용하여 폼을 통해 같은 단계를 진행합니다. 일반 API 키를 사용하는 공급자는 이 모든 과정을 건너뜁니다. PUT /api/connections/<service>을 {"authType":"api_key","values":{"apiKey":"..."}}과 함께 사용하면 키를 직접 저장할 수 있습니다.

각 에이전트에 런타임 토큰을 부여하고 자격 증명은 절대 공유하지 마십시오

에이전트는 관리자 API가 생성한 런타임 토큰을 사용하여 게이트웨이에 인증합니다.

curl -s -X POST https://connect.example.com/api/runtime-tokens \
  -H "authorization: Bearer $ADMIN_TOKEN" \
  -H 'content-type: application/json' \
  -d '{"name":"research-agent"}'

응답에는 oct_로 시작하는 토큰이 포함됩니다. 에이전트마다 하나씩 발급하고 해당 에이전트의 이름을 따서 명명하십시오. 식별할 수 없는 토큰을 취소한다는 것은 모든 토큰을 취소한다는 의미이기 때문입니다. 이후 에이전트는 일반 HTTP를 통해 작업을 호출합니다.

curl -s -X POST https://connect.example.com/v1/actions/github.get_current_user \
  -H "authorization: Bearer oct_..." \
  -H 'content-type: application/json' \
  -d '{"input":{}}'

정상적인 응답은 success 필드가 true이고 data 아래에 공급자 페이로드가 포함된 봉투 형태입니다. GitHub 토큰은 해당 응답 어디에도 포함되지 않습니다. MCP 클라이언트의 경우 동일한 bearer 헤더를 사용하여 https://connect.example.com/mcp를 가리키도록 설정하십시오. 그러면 게이트웨이는 API당 하나의 도구가 아닌 search_actions 및 execute_action와 같은 검색 도구를 제공하므로 에이전트의 도구 목록을 간결하게 유지할 수 있습니다. VPS에서 MCP 서버 실행하기에서 해당 연결의 클라이언트 측 설정을 다룹니다.

작업을 완료하기 전에 한 번 더 확인하십시오. authorization 헤더를 삭제한 상태에서 작업 호출을 반복하십시오. 프로젝트 자체의 퀵스타트 가이드는 bearer 없이 /v1을 호출하므로, 런타임 인증이 구성되지 않은 상태로 설치하면 해당 포트에 접근할 수 있는 누구라도 작업을 실행할 수 있습니다. 인증되지 않은 호출이 성공한다면 두 가지 해결 방법이 있습니다. 런타임 토큰을 구성하여 익명 호출이 실패하는지 확인하거나, 리버스 프록시에서 /api, /v1 및 /mcp에 대한 접근을 에이전트가 위치한 주소로 제한하십시오. 오직 /oauth/callback만 외부로 열려 있어야 합니다. 이는 공급자의 브라우저 리다이렉트가 필요한 유일한 경로이기 때문입니다.

에이전트가 필요한 작업 목록으로 제한하기

수천 개의 제공자를 배후에 둔 게이트웨이는 언어 모델에 노출하기에는 너무 넓은 공격 표면입니다. 모델이 직접 작성하지 않은 텍스트를 읽기 시작하는 순간 이 표면은 더욱 넓어집니다. 에이전트의 웹 검색에 응답하는 자체 SearXNG 인스턴스가 반환한 페이지에는 에이전트가 가진 모든 작업에 대한 명령이 포함될 수 있기 때문입니다. 코딩 에이전트가 작동하는 가장 작은 변경 사항만 적용하도록 제한하는 것과 같은 원칙이 권한 설정에도 적용되어야 합니다. 업무에 실제로 필요한 몇 가지 작업만 허용하고 그 외의 것은 허용하지 마십시오. 두 가지 제어 설정으로 이를 제한할 수 있습니다.

OOMOL_CONNECT_ALLOWED_ACTIONS은 쉼표로 구분된 허용 목록을 받으며 service.* 및 *을 이해합니다. OOMOL_CONNECT_BLOCKED_ACTIONS는 차단 목록이며, 차단 목록이 우선합니다. 허용 목록을 github.get_current_user,github.list_issues로 설정하면 에이전트의 요청과 관계없이 다른 모든 작업이 거부되므로, 단순한 실수와 보안 사고를 가르는 결정적인 차이가 됩니다. 런타임 토큰은 전역 규칙 위에 자체적인 작업 규칙을 가지며, 해당 allowedProxies 목록은 기본적으로 비어 있으므로 권한을 부여하기 전까지 POST /v1/proxy/:service은 거부됩니다. 해당 프록시 엔드포인트는 귀하의 자격 증명을 첨부하여 원시 요청을 제공자에게 전달하므로, 특정 에이전트가 반드시 필요한 경우가 아니라면 비워 두십시오.

OOMOL_CONNECT_ALLOW_PRIVATE_NETWORK은 기본값이 false이며, 이는 자체 호스팅된 제공자 연결이 169.254.169.254의 클라우드 메타데이터 서비스나 동일 네트워크상의 데이터베이스와 같은 사설 주소를 가리키지 못하도록 차단합니다. 이 설정을 끄십시오. 직접 호스팅하는 제공자에 대해서만 이 설정을 켜십시오.

모든 토큰이 저장된 서버 백업하기

두 가지가 중요하며, 각각은 서로 없으면 무용지물입니다. connector-data 볼륨 내부의 /app/data/connect.sqlite에 있는 데이터베이스는 봉인된 자격 증명을 보관합니다. .env에 있는 암호화 키는 이를 해제합니다. 키가 없는 볼륨 백업으로는 아무것도 복구할 수 없으며, 볼륨이 없는 키로도 아무것도 복구할 수 없습니다. 따라서 키는 비밀번호 관리자에 보관하고 볼륨은 일반적인 백업 주기에 포함해야 합니다.

SQLite 파일을 복사하는 동안에는 컨테이너를 중지하십시오. 쓰기 작업 중에 복사본을 생성하면 데이터베이스가 손상된 상태로 복구될 수 있습니다.

docker volume ls | grep connector-data
docker compose stop connector
docker run --rm -v open-connector_connector-data:/data -v "$PWD":/backup alpine \
  tar czf /backup/connector-data.tgz -C /data .
docker compose start connector

볼륨 이름은 프로젝트 디렉터리에 _connector-data를 더한 값입니다. 첫 번째 명령어가 존재하는 이유가 바로 이것이며, 실제 이름을 세 번째 명령어에 붙여넣으십시오. 아카이브는 VPS에서 restic 백업을 사용하여 VPS 외부로 전송하십시오. 이 아카이브는 자격 증명 저장소이므로 외부로 나가기 전에 암호화됩니다.

런타임은 최근 작업 실행 기록을 감사 기록으로 유지하며, 기본값은 5,000개입니다. 따라서 콘솔을 통해 어떤 에이전트가 무엇을 언제 실행했는지 확인할 수 있습니다. 에이전트가 이상하게 동작할 때 가장 먼저 읽어야 할 것이 바로 이 로그입니다. 또한 https://connect.example.com/health를 Uptime Kuma 상태 페이지에 연결하십시오. 게이트웨이가 응답을 멈추면 에이전트는 혼란스러운 방식으로 실패합니다. 게이트웨이가 중단되었음을 미리 알면 에이전트 출력을 읽느라 허비하는 시간을 한 시간 정도 절약할 수 있습니다.

발생하는 문제와 표시되는 메시지

제공업체 측의 redirect_uri_mismatch. 오리진과 등록된 콜백 URL이 일치하지 않습니다. /api/oauth/configs의 정확한 문자열을 제공업체의 앱 설정과 비교하십시오. 이때 https과 http를 포함하여 마지막 슬래시(/) 여부까지 확인해야 합니다.

모든 /api 호출이 401을 반환함. 관리자 토큰 헤더가 누락되었거나 오타가 있습니다. 헤더는 Authorization: Bearer <token>이며, 웹 콘솔에서도 동일한 토큰을 요구합니다.

컨테이너는 실행되지만 자격 증명이 평문으로 저장됨. 이는 OOMOL_CONNECT_ENCRYPTION_KEY가 컨테이너에 도달하지 못했을 때 발생합니다. 런타임이 실행을 거부하는 대신 자격 증명 레코드를 암호화하지 않고 저장하기 때문입니다. 직접 설치한 환경에서 확인하려면, 식별 가능한 API 키로 제공업체를 연결한 뒤 데이터베이스에서 해당 키를 검색해 보십시오.

docker compose cp connector:/app/data/connect.sqlite /tmp/connect.sqlite
grep -c 'github_pat_' /tmp/connect.sqlite
shred -u /tmp/connect.sqlite

검색 결과가 0보다 크면 키가 적용되지 않은 상태입니다. .env이 compose.yaml와 같은 디렉터리에 있는지, 그리고 docker compose config가 해당 값을 표시하는지 확인하십시오. 키가 올바르게 설정되면 동일한 검색 결과는 0이 됩니다. 레코드가 AES-256-GCM(Advanced Encryption Standard, 256비트 키, Galois/Counter Mode)으로 봉인되기 때문입니다.

복원 후 아무것도 복호화되지 않음. 암호화 키가 변경되었거나 분실되었습니다. 설계상 키는 데이터와 함께 저장되지 않으므로 복구 경로가 없으며 지원 티켓으로도 해결할 수 없습니다. 모든 제공업체를 다시 연결하십시오. 키 교체는 별도의 키 변수와 런타임의 데이터 명령을 통해 지원되므로, 교체 작업을 수행하기 전에 현재 릴리스 노트를 읽어보십시오.

에이전트가 카탈로그에서 확인할 수 있는 작업에 대해 오류를 반환함. 검색(Discovery)과 실행(Execution)은 별개의 과정입니다. 작업이 search_actions에는 나타날 수 있지만, OOMOL_CONNECT_ALLOWED_ACTIONS, 거부 목록(denylist), 또는 해당 런타임 토큰 자체의 규칙에 의해 거부될 수 있습니다.

업그레이드. 볼륨을 백업하고 이미지 태그를 새 릴리스로 수정한 다음 docker compose pull && docker compose up -d을 실행하십시오. docker compose logs -n 50 connector에서 마이그레이션 로그를 확인하고, 다시 신뢰하기 전에 상태 점검과 실제 작업을 한 번 수행하십시오. 롤백은 이전 태그로 되돌리는 것을 의미하며, 태그를 고정(pin)해 두었을 때만 정상적으로 작동합니다.

FAQ

Open Connector를 셀프 호스팅하려면 공인 도메인이 필요한가요?

API 키를 사용하는 제공자의 경우, 127.0.0.1의 게이트웨이만으로도 충분하므로 필요하지 않습니다. 하지만 OAuth를 사용한다면 실질적으로 필요합니다. 제공자가 브라우저를 콜백 URL로 리다이렉트하므로 해당 URL은 공인 인터넷에서 해석 가능해야 하며, 제공자들은 localhost를 제외한 일반 http:// 연결을 거부하기 때문입니다. 첫 실행 전에 OOMOL_CONNECT_ORIGIN를 본인의 https:// 호스트네임으로 설정하고, 제공자의 OAuth 앱에 <origin>/oauth/callback를 등록하십시오.

Open Connector 암호화 키를 분실하면 어떻게 되나요?

저장된 자격 증명을 복호화할 수 없으며, 복구 방법도 없습니다. 이 키는 데이터와 함께 저장되지 않도록 설계되었으므로 데이터베이스를 탈취한 공격자나 사용자 본인조차 내용을 읽을 수 없습니다. 유일한 해결책은 새 키를 설정하고 모든 제공자를 다시 연결하는 것뿐입니다. 키는 비밀번호 관리자에 보관하고 데이터베이스는 백업 로테이션에 포함하십시오. 복구 시 두 가지 모두 필요하기 때문입니다.

AI 에이전트가 제공자 액세스 토큰을 볼 수 있나요?

게이트웨이를 통해 호출하는 경우에는 볼 수 없습니다. 에이전트는 oct_로 시작하는 런타임 토큰으로 인증하며, 게이트웨이가 서버 측에서 아웃바운드 요청에 제공자 자격 증명을 주입한 뒤 응답만 반환하기 때문입니다. 이 보안 원칙이 깨지는 경우는 두 가지입니다. 자격 증명이 포함된 원시 요청을 전달하는 /v1/proxy/:service 엔드포인트(이 엔드포인트의 권한이 기본적으로 비어 있는 이유입니다)와, 게이트웨이를 완전히 우회하여 API 키를 에이전트에 직접 붙여넣는 경우입니다.

게이트웨이를 공인 인터넷에서 접근 가능하게 해야 하나요?

/oauth/callback만 접근 가능하면 됩니다. 컨테이너 포트를 127.0.0.1에 게시하여 Docker의 NAT 규칙이 방화벽 너머로 포트를 노출하지 않도록 하고, 앞단에 리버스 프록시를 배치하십시오. 그 후 authorization 헤더 없이 액션 호출을 하나 테스트해 보십시오. 성공한다면, 인증된 호출만 작동할 때까지 프록시에서 /api, /v1, /mcp를 에이전트가 사용하는 주소로 제한하십시오.

Open Connector는 프로덕션 환경에서 사용할 준비가 되었나요?

Apache 2.0 라이선스를 따르며 빠르게 발전하고 있습니다. 저장소는 2026년 6월 29일에 공개되었고 v1.3.3은 2026년 7월 30일에 출시되었으므로, 이 가이드의 모든 버전 번호는 2026년 8월 1일 기준의 스냅샷으로 간주하십시오. 항상 릴리스 태그에 고정하여 실행하고 latest이나 tip 태그는 사용하지 마십시오. 업그레이드 전에는 릴리스 노트를 읽고, 최소 한 번 이상 복구 테스트를 거친 볼륨 백업을 유지하십시오. 직접 관리하는 서버라면 설계는 견고하며, 위험 요소는 아키텍처가 아닌 잦은 버전 변경입니다.

이 글이 도움이 되었나요?

#ai-agents #oauth #self-hosting#integrations#open-source