가이드

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

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

Q: Do I need a public domain to self-host Open Connector?

For providers that use an API key, no: a gateway on 127.0.0.1 is enough. For OAuth, yes in practice. The provider redirects a browser to your callback URL, so that URL has to resolve from the public internet, and providers refuse plain http:// outside localhost. Set OOMOL_CONNECT_ORIGIN to your https:// hostname before the first start, and register /oauth/callback in the provider's OAuth app.

Q: Should the gateway be reachable from the public internet?

Only /oauth/callback has to be. Publish the container port on 127.0.0.1 so Docker's NAT rules cannot expose it past your firewall, and put the reverse proxy in front. Then test one action call with no authorization header. If it succeeds, restrict /api, /v1 and /mcp at the proxy to the addresses your agents use until authenticated calls are the only ones that work.

AI 에이전트가 SaaS 토큰을 직접 보유하지 않도록 Open Connector를 VPS에 직접 호스팅하는 방법을 설명합니다. OAuth 콜백 설정, TLS 오리진 구성, SQLite 데이터 백업 등 보안 강화를 위한 필수 단계를 상세히 안내합니다.

AI 에이전트를 위한 Open Connector의 역할

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

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

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

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

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

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

시작하기 전에 비용을 명확히 인지하십시오. 이 VPS는 운영 중인 서버 중 가장 중요한 서버가 됩니다. 여러 서비스의 유효한 자격 증명을 하나의 파일에 보관하므로, 비밀번호 관리자 호스트를 다루는 수준의 관리가 필요합니다. 443 포트만 개방하는 방화벽 설정, 공유 로그인 금지, 실제로 복구 테스트를 완료한 백업, 그리고 응답이 없을 때 발생하는 알림 설정이 필수적입니다. 만약 비밀번호 저장소를 해당 장비에 둘 생각이 없다면, 커넥터 역시 설치하지 마십시오.

설치 전 버전을 고정하십시오

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

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

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

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

Ubuntu 24.04 또는 유사한 환경의 Docker 및 Compose 플러그인
이 VPS를 가리키는 A 레코드를 가진 호스트 이름(예: 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라는 줄이 출력된다면 포트 매핑이 여전히 업스트림 설정 상태이며, 게이트웨이가 인터넷 전체에 직접 응답하고 있다는 의미입니다. 상태 확인에서 연결 거부(Connection refused)가 발생하면 컨테이너가 아직 수신 대기 중이 아니라는 뜻이므로, 프록시를 건드리기 전에 로그를 먼저 확인하십시오.

동일한 서비스를 위한 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)으로 봉인되기 때문입니다.

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

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

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

FAQ

Do I need a public domain to self-host Open Connector?

For providers that use an API key, no: a gateway on 127.0.0.1 is enough. For OAuth, yes in practice. The provider redirects a browser to your callback URL, so that URL has to resolve from the public internet, and providers refuse plain http:// outside localhost. Set OOMOL_CONNECT_ORIGIN to your https:// hostname before the first start, and register <origin>/oauth/callback in the provider's OAuth app.

What happens if I lose the Open Connector encryption key?

The stored credentials cannot be decrypted, and there is no recovery. The key is deliberately never stored alongside the data, so nobody holding the database can read it, including you. Your only option is to set a new key and reconnect every provider. Keep the key in a password manager and the database in your backup rotation, because a restore needs both.

Can my AI agent see the provider access token?

Not when it calls through the gateway. The agent authenticates with a runtime token starting oct_, and the gateway injects the provider credential into the outbound request on the server, returning only the response. Two things break that property: the /v1/proxy/:service endpoint, which forwards raw requests with your credential attached and whose grants start empty for a reason, and pasting an API key into the agent yourself, which skips the gateway entirely.

Should the gateway be reachable from the public internet?

Only /oauth/callback has to be. Publish the container port on 127.0.0.1 so Docker's NAT rules cannot expose it past your firewall, and put the reverse proxy in front. Then test one action call with no authorization header. If it succeeds, restrict /api, /v1 and /mcp at the proxy to the addresses your agents use until authenticated calls are the only ones that work.

Is Open Connector ready for production use?

It is Apache 2.0 licensed and moving fast: the repository appeared on 29 June 2026 and v1.3.3 shipped on 30 July 2026, so treat every version number in this guide as a snapshot of 1 August 2026. Run it pinned to a release tag, never on latest or tip, read the release notes before each upgrade, and keep a volume backup you have restored once. The design is sound for a box you own, and the risk is the version churn, not the architecture.

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