가이드

작성자 Matt Connor 2026-08-01

Open Connector 직접 호스팅하여 AI 에이전트 보안 강화하기

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를 직접 호스팅하여 AI 에이전트가 SaaS 토큰을 직접 보유하지 않도록 설정하십시오. TLS 설정, OAuth 콜백 처리, 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 에이전트에서 비밀 정보를 보호하는 방법에서 설명하는 장애가 발생하는 기록(transcript)에 남게 됩니다.

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

카탈로그는 1,000개 이상의 공급자와 10,000개 이상의 사전 구축된 작업을 광고하는데, 이는 프로젝트 자체 수치이며 외부에서 검증할 수 있는 내용은 아닙니다. 검증 가능한 것은 구조입니다. 작업당 하나의 HTTP 엔드포인트, 공급자당 하나의 저장된 연결, 에이전트당 하나의 토큰이 그것입니다.

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

호스팅되는 커넥터 서비스는 동일한 작업을 수행하며, 연결된 모든 공급자에 대한 갱신 토큰(refresh token)을 보관합니다. 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 플러그인
이 VPS를 가리키는 A 레코드가 있는 호스트 이름 (예: connect.example.com)
해당 호스트 이름에 대해 이미 TLS(전송 계층 보안)를 종료하는 리버스 프록시
아래에서 생성할 두 개의 임의 보안 비밀(secret)

여러 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>/oauth/callback 형식의 리디렉션 URI를 생성합니다. 이 값을 설정하지 않으면 오리진은 기본값인 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:// 주소를 거부합니다. 이것이 바로 이 배포 환경에 호스트 이름과 인증서가 필요한 이유입니다. 오리진 값은 시작 시점에 읽히므로 첫 실행 전에 설정해야 합니다. .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 키를 사용하는 제공자는 이 모든 과정을 건너뜁니다. {"authType":"api_key","values":{"apiKey":"..."}}을 사용한 PUT /api/connections/<service>은 키를 직접 저장합니다.

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

에이전트는 관리자 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만 외부로 열려 있어야 합니다. 이는 공급자의 브라우저 리디렉션에 필요한 유일한 경로이기 때문입니다.

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

수천 개의 공급자가 연결된 게이트웨이는 언어 모델에 노출되는 공격 표면이 넓습니다. 두 가지 제어 항목으로 이를 좁힐 수 있습니다.

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개까지 유지합니다. 따라서 콘솔을 통해 어떤 에이전트가 무엇을 언제 실행했는지 확인할 수 있습니다. 에이전트가 비정상적으로 동작할 때 가장 먼저 읽어야 할 것이 바로 이 로그입니다. Uptime Kuma 상태 페이지를 https://connect.example.com/health로 지정하십시오. 게이트웨이가 응답을 멈추면 에이전트는 혼란스러운 방식으로 실패합니다. 게이트웨이가 다운되었음을 미리 알면 에이전트 출력을 읽느라 낭비하는 시간을 한 시간가량 줄일 수 있습니다.

무엇이 중단되며, 어떤 메시지가 표시되는가

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(고급 암호화 표준, 256비트 키, 갈루아/카운터 모드)으로 봉인되기 때문입니다.

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

에이전트가 카탈로그에서 확인할 수 있는 작업에 대해 오류를 반환함. 검색과 실행은 별개의 과정입니다. 작업이 search_actions에 표시되더라도 OOMOL_CONNECT_ALLOWED_ACTIONS, 차단 목록, 또는 해당 런타임 토큰 자체의 규칙에 의해 거부될 수 있습니다.

업그레이드. 볼륨을 백업하고 이미지 태그를 새 릴리스로 수정한 다음 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