프라이빗 인프라, 공개 URL 없이 OpenAI에 터널 연결 가능

v2.43.0: tunnel_id와 방화벽 인프라에서 OpenAI 연결하기

openai v2.43.0의 핵심 추가 기능은 tunnel_id로, MCP 도구를 연결하는 세 번째 방법입니다. 2026년 6월 17일에 출시된 이 릴리스는 2개의 커밋과 14개의 변경 파일로 구성되며, 대부분 버전 메타데이터와 Responses·Realtime MCP 도구 형식 전반의 자동 생성된 타입 변경으로 이루어져 있습니다 . 실질적인 변경 사항은 tunnel_id 하나입니다.

tunnel_id는 기존의 server_url, connector_id와 함께 설정 옵션으로 추가되며, 타입 계약은 엄격합니다. 세 가지 중 정확히 하나만 지정해야 하며, 조합은 허용되지 않습니다 .

이 기능이 유용한 이유는 동작 방식에 있습니다. tunnel-client가 OpenAI로 아웃바운드 HTTPS를 열고 JSON-RPC 작업을 long-poll로 수신한 뒤, 각 요청을 로컬에서 실행하고 결과를 터널을 통해 반환합니다 . 서버 자체에는 인바운드 포트나 공개 엔드포인트가 전혀 필요 없으며, 연결은 전적으로 클라이언트 측에서 시작됩니다.

이로써 기존에는 Responses API, ChatGPT, Codex 뒤에 둘 수 없었던 대상들이 연결 가능해집니다:

• 테스트 중 로컬 MCP 서버를 실행 중인 개발자 머신
• 사내 네트워크 내부의 온프레미스 서버
• 공개 인터넷으로의 경로가 없는 방화벽 인프라
• 보안 또는 정책상 이유로 공개 URL을 노출해서는 안 되는 MCP 서버

v2.42.0의 지출 알림, 만료, 감사 필터링

한 릴리스 앞선 v2.42.0은 두 버전 중 더 큰 diff였습니다: 8개의 커밋과 26개의 변경 파일로, v2.43.0의 2개 커밋·14개 파일과 대비됩니다. 핵심 추가 기능은 spend_alerts로, 예산 관리를 위한 프로그래밍 방식의 Admin API 리소스입니다. 조직 레벨(/organization/spend_alerts)과 프로젝트 레벨(/organization/projects/{project_id}/spend_alerts) 모두에서 생성·조회·수정·목록·삭제의 전체 CRUD를 제공하며, 어드민 API 키 인증이 필요합니다 [ref].

두 범위는 서로 다른 객체를 반환합니다. 조직 전체 예산에는 organization.spend_alert, 프로젝트별 예산에는 project.spend_alert가 사용됩니다. 알림 형식은 간결하므로 연결 전에 읽어두는 것이 좋습니다:

센트 기반의 threshold_amount는 실수하기 쉬운 부분입니다. $50 예산은 50이 아니라 5000으로 입력해야 합니다 [ref].

v2.42.0은 키·감사 거버넌스도 강화했습니다. Admin API 키 생성에 expires_in_seconds가 추가되었고, 키 모델에 expires_at이 포함되어 코드에서 단기 어드민 자격증명을 발급할 수 있게 되었습니다. 더 이상 자격증명이 무기한 유효하지 않아도 됩니다. 감사 로그 필터링에는 tenant_only 플래그와 두 가지 테넌트 범위 역할 이벤트(role.bound_to_resource, role.unbound_from_resource)가 추가되었으며, ChatGPT 워크스페이스 커넥터 리소스 ID를 <workspace_id>__<connector_id> 형식으로 표시합니다 [ref].

핵심은 이 변경 사항 중 일반적인 모델 호출에 영향을 미치는 것은 없다는 점입니다. v2.42.0은 플랫폼 어드민 및 거버넌스 영역의 변경으로, 조직 단위 지출과 접근 권한을 관리하는 팀에게 중요하며, 그 외 사용자는 건너뛰어도 무방합니다 [ref].

직전 스프린트: Responses와 Chat Completions의 콘텐츠 검수

2주 전으로 거슬러 올라가도 동일한 점진적 추가 패턴이 이어집니다. 2026년 6월 3일에 출시된 v2.41.0은 두 곳에 동시에 인라인 콘텐츠 검수를 도입했습니다 — responses.moderation과 chat_completions.moderation입니다 . 개발자 입장에서의 이점은 왕복 횟수 감소입니다. 검수 객체가 완성 결과와 함께 반환되므로, 동일한 텍스트를 검사하기 위해 별도의 Moderation API를 호출할 필요가 없어집니다.

이틀 앞선 v2.40.0(2026년 6월 1일)에서는 Amazon Bedrock Responses 지원이 추가되었고, Bedrock API 키를 클라이언트 객체에 직접 설정할 수 있는 수정이 이루어져 AWS 사용자에게 기존의 환경변수 전용 우회 방법이 더 이상 필요하지 않게 되었습니다 .

순서대로 읽으면, 6월 스프린트는 단일 API 형식을 반복 개선한 것이 아닙니다. 각 마이너 릴리스는 독립된 레이어를 추가합니다:

• v2.40.0 — 클라우드 공급자 연동 확장 (Bedrock Responses)
• v2.41.0 — Responses·Chat Completions 인라인 검수
• v2.42.0 — 어드민 거버넌스 (지출 알림, 키 만료, 감사 필터링)
• v2.43.0 — tunnel_id를 통한 사설 네트워크 연결

4개의 릴리스, 4가지 독립된 관심사 — SDK가 하나의 기능을 재작업하는 것이 아니라 업스트림 스키마 추가를 추적하고 있을 때 정확히 예상할 수 있는 모습입니다.

Spec 드리프트가 릴리스 주기를 결정하는 원리

네 개의 릴리스가 서로 무관한 네 가지 사항을 담고 있는 이유는 구조적인 데 있습니다: SDK가 코드 자동 생성 방식으로 만들어지기 때문입니다. 각 릴리스 커밋에는 동일한 changelog 항목이 포함됩니다 — update OpenAPI spec or Stainless config — Stainless가 OpenAI의 OpenAPI 명세로부터 직접 openai 패키지를 재생성하기 때문입니다 . 업스트림 명세나 Stainless 생성기 설정에 변경이 생기면, 사람이 기능 코드를 직접 작성하지 않아도 새 릴리스가 자동으로 트리거됩니다.

이 자동화가 릴리스 템포를 설명합니다. 2026년 6월 17일까지 한 달간의 기록을 보면 마이너 릴리스가 다섯 번 이루어졌습니다: 6월 1일에 v2.39.0과 v2.40.0, 6월 3일에 v2.41.0, 6월 16일에 v2.42.0, 6월 17일에 v2.43.0, 그리고 패치 v2.41.1이 있었습니다 . 연속된 날에 마이너 두 개가 출시된 것은 우연이 아닙니다 — spec-push 자동화가 만들어내는 당연한 결과입니다.

"update OpenAPI spec or Stainless config" — openai-python CHANGELOG에 반복되는 릴리스 문구.

파이프라인 자체도 스프린트 중간에 조정되었습니다. v2.41.1은 "예약된 릴리스 워크플로우 트리거를 제거"했고, v2.42.0은 "릴리스 워크플로우 권한을 수정"했습니다 — 팀은 마지막 수동 스케줄 설정을 제거해 spec 변경 사항이 바로 발행으로 이어지도록 했습니다.

이런 간결함의 대가: "update OpenAPI spec"이라는 표현은 각 diff 뒤에 숨겨진 실제 서버 측 변경 사항을 드러내지 않으며, 이는 항상 공개적으로 문서화되지도 않습니다. 진짜 신호를 얻으려면 태그 노트 대신 GitHub compare 뷰를 확인하세요 — v2.42.0...v2.43.0 delta는 두 개의 커밋과 14개의 변경된 파일만을 보여주지만 , changelog 줄이 전달하는 것보다 훨씬 많은 정보를 담고 있습니다.

버전 제약 조건 살펴보기

v2.40부터 v2.43까지의 모든 릴리스는 SemVer 마이너로, 추가 사항이 하위 호환성을 유지하도록 설계되었음을 의미합니다 — 해당 범위 전체에 걸쳐 문서화된 파괴적 변경(breaking change)은 없습니다 . tunnel_id, spend_alerts, Responses 조정(moderation) 같은 새로운 타입 형태는 기존 필드를 제거하지 않고 인터페이스를 확장하므로, 대부분의 호출자에게 2.x 내 업그레이드는 가산적(additive)으로 이루어집니다.

대가는 잦은 변경입니다. 21일 동안 마이너 다섯 개가 출시됐고 — 2026년 6월 1일부터 6월 17일까지 — Dependabot이나 Renovate로 최신 버전을 추적하면 주당 약 하나의 병합 요청이 생깁니다 . 정확한 버전을 고정한 팀(openai==2.42.0)은 간결한 update OpenAPI spec 태그만으로는 우선순위를 가늠하기 어려운 버전 업 PR을 꾸준히 받게 됩니다.

실용적인 접근법:

• 호환되는 마이너 범위로 고정하세요: openai>=2.40,<3.
• 버전을 올릴 때마다 GitHub compare diff를 확인하세요 — v2.42.0...v2.43.0 delta는 두 개의 커밋과 14개의 변경된 파일을 보여줍니다 .
• 동일하다고 가정하기 전에 생성된 타입 파일에서 새 필드를 grep으로 확인하세요.

핵심 교훈: changelog 태그를 요약본이 아닌 포인터로 다루세요 — 실제 신호는 compare 뷰에 있습니다.

자주 묻는 질문

MCP 도구 설정에서 tunnel_id란 무엇이며 server_url과 어떻게 다른가요?

tunnel_id는 openai-python v2.43.0에서 Responses 및 Realtime MCP 도구 형태에 추가된 필드입니다 . 이 필드는 MCP 호출을 OpenAI의 보안 MCP 터널을 통해 라우팅합니다. 로컬 tunnel-client가 OpenAI로 아웃바운드 HTTPS를 열고 작업을 롱폴링하므로, MCP 서버에 공개 엔드포인트가 필요하지 않습니다 . 반면 server_url은 접근 가능한 공개 서버를 가리키고, connector_id는 OpenAI가 관리하는 커넥터 래퍼(Google Workspace, Dropbox 등)를 대상으로 합니다 . 타입 계약상 셋 중 정확히 하나만 지정해야 합니다.

v2.42.0부터 OpenAI 지출 알림을 프로그래밍 방식으로 생성·관리할 수 있나요?

네. v2.42.0에서 관리자용 spend_alerts 리소스가 추가되어 생성, 조회, 수정, 목록, 삭제 메서드를 제공합니다 . 엔드포인트는 조직 레벨(/organization/spend_alerts)과 프로젝트 레벨(/organization/projects/{project_id}/spend_alerts) 모두 제공됩니다 . 알림에는 currency: USD, interval: month, 센트 단위의 threshold_amount(최솟값 0), 이메일 notification_channel을 사용합니다. 인증 요구 사항에 유의하세요: 이 호출에는 일반 사용자 키가 아닌 관리자 API 키가 필요합니다.

openai-python SDK는 왜 이렇게 자주 릴리스되며 변경 로그가 간결한가요?

이 SDK는 OpenAI의 OpenAPI 명세에서 Stainless가 코드를 자동 생성하므로, 업스트림 명세에 변경이 생기면 수작업 기능 개발이 아닌 자동화된 릴리스 커밋이 트리거됩니다 . 그래서 변경 로그에 update OpenAPI spec or Stainless config라는 문구가 반복되고, 2026년 6월에만 마이너 릴리스가 다섯 차례 이루어진 것입니다 . 또한 v2.41.1에서 예약된 릴리스 워크플로 트리거를 제거하여 이제 명세 변경 이벤트가 발생하는 즉시 버전이 배포됩니다 — 작은 스키마 변경만으로도 새 마이너 버전이 생성됩니다.

마이그레이션 가이드 없이 v2.40에서 v2.43으로 업그레이드해도 안전한가요?

대체로 안전합니다. 이는 2.x 내의 SemVer 마이너 버전으로, Stainless가 생성한 추가 사항이며 하위 호환성을 유지하도록 설계되었고, 문서화된 주요 변경 사항도 없습니다 . 주의할 점은 생성된 타입을 직접 임포트하는 코드입니다. tunnel_id나 expires_in_seconds 같은 새로운 선택적 필드가 엄격한 타입 단언에 영향을 미칠 수 있습니다. 동등성을 가정하기 전에 GitHub 비교 diff를 확인하세요 — v2.42.0...v2.43.0 델타는 커밋 2개와 변경 파일 14개입니다 . 변경된 타입 파일에서 새 필드를 Grep으로 확인한 후 업그레이드하세요.