ChatGPT 플러그인 개발, 이제 GPTs Actions로! 초보자를 위한 첫 API 연동 가이드

ChatGPT 플러그인 개발, 이제 GPTs Actions로! 초보자를 위한 첫 API 연동 가이드

ChatGPT 플러그인 문서를 참고해서 뭔가 만들어보려고 했다가 "이 기능은 더 이상 지원되지 않습니다"라는 메시지를 본 적 있다면, 그건 당신만 겪은 일이 아니다.

OpenAI는 2024년 4월 9일 ChatGPT 플러그인을 공식 종료했다. 그 이후로 외부 API와 ChatGPT를 연동하는 방식은 GPTs Actions로 완전히 이전됐다. 막상 GPTs Actions 문서를 열어보면 OpenAPI 스키마 작성, 인증 방식 설정 같은 내용이 쏟아지는데, 어디서부터 시작해야 할지 막막한 게 당연하다.

이 글은 플러그인을 써본 사람이든 API 연동 자체가 처음인 사람이든, GPTs Actions로 외부 API를 연결하는 전체 흐름을 처음부터 짚어주는 가이드다. 개념 설명에 그치지 않고, 실제 설정 화면 기준으로 뭘 어디에 입력해야 하는지까지 다룬다.

---

ChatGPT 플러그인은 왜 사라졌나

플러그인이 처음 등장했을 때는 꽤 기대됐다. ChatGPT가 외부 서비스와 연결돼서 날씨 정보를 가져오거나, 여행 예약을 하거나, 코드 실행까지 할 수 있다는 얘기였으니까. 실제로 2023년 초부터 플러그인 스토어가 열리고 수백 개의 플러그인이 등록됐다.

그런데 써보면 생각보다 불편한 점이 많았다. 우선 플러그인을 사용하려면 매번 대화를 시작할 때 직접 활성화해야 했고, 동시에 켤 수 있는 플러그인 수도 제한돼 있었다. 개발자 입장에서는 플러그인을 만들어 스토어에 올리는 과정이 복잡했고, 승인 절차도 있었다. 무엇보다 플러그인이 ChatGPT의 전반적인 대화 흐름과 자연스럽게 연결되지 않는다는 느낌이 강했다.

결국 OpenAI는 플러그인 방식 대신 GPTs라는 커스터마이징 플랫폼을 전면에 내세우고, 외부 API 연동 기능은 GPTs 안의 Actions로 통합했다. 2024년 3월 19일부터 플러그인으로 새 대화를 시작할 수 없게 됐고, 4월 9일에는 기존 플러그인 대화도 모두 종료됐다. 지금은 ChatGPT에서 플러그인 메뉴 자체가 없어진 상태다.

OpenAI 공식 Deprecations 문서에서 확인할 수 있듯이, 이 전환은 일시적인 게 아니라 영구적인 구조 변경이다. 지금 외부 API와 ChatGPT를 연동하고 싶다면 GPTs Actions 외에 다른 선택지는 없다.

---

GPTs Actions란 무엇인가 — 플러그인과 뭐가 다른가

GPTs Actions는 Custom GPT(나만의 GPT) 안에 외부 API 호출 기능을 내장하는 방식이다. 사용자가 자연어로 대화를 하면, GPT가 그 의도를 파악해서 지정된 API를 자동으로 호출하고, 결과를 다시 자연어로 응답하는 구조다.

플러그인과 비교하면 몇 가지 차이점이 있다.

플러그인 방식은 ChatGPT 본체에 기능을 추가하는 형태였다. 누구나 같은 플러그인을 쓰고, 플러그인 스토어에서 설치하는 방식이었다. 반면 GPTs Actions는 특정 Custom GPT에 귀속된 기능이다. 내가 만든 GPT에만 붙어있고, 그 GPT를 쓰는 사람만 해당 API 기능을 활용할 수 있다.

이 차이가 실제로는 더 유연하게 느껴진다. 플러그인은 불특정 다수에게 공개되는 공용 도구였지만, GPTs Actions는 특정 목적에 맞게 설계된 전용 에이전트를 만들 수 있다. 예를 들어 "우리 회사 내부 API에서 데이터를 가져오는 GPT"를 팀 내부용으로 만드는 것도 가능하다.

기술적으로는 OpenAPI 스키마(API 명세를 표준 형식으로 작성한 문서)를 GPT에 등록하면, GPT가 그 스키마를 읽고 "이 상황에서는 이 API를 호출하면 되겠구나"를 스스로 판단한다. 개발자가 일일이 "이때 이 함수를 호출해라"고 코딩하는 게 아니라, GPT가 문맥에 따라 알아서 API를 선택하고 파라미터를 채워 넣는 방식이다.

현재(2026년 기준) Actions가 포함된 Custom GPT는 GPT-4o와 GPT-4.1 모델에서만 안정적으로 동작한다. Action이 없는 일반 GPT는 여러 모델을 선택할 수 있지만, API 연동 기능을 넣으면 모델 선택이 제한된다는 점은 알아두는 게 좋다.

---

GPTs Actions 기본 설정 흐름 — 처음부터 끝까지

직접 해보기 전에는 막막해 보이지만, 흐름을 한 번 파악하면 반복 작업이 된다. 크게 네 단계다.

1단계 — Custom GPT 만들기

ChatGPT 좌측 사이드바에서 "GPTs 탐색" → 오른쪽 상단 "만들기" 버튼을 클릭한다. GPT 빌더 화면이 뜨는데, 두 가지 탭이 있다. "만들기" 탭은 대화형으로 설정을 도와주고, "구성" 탭은 직접 세부 항목을 입력하는 화면이다. Actions 설정은 "구성" 탭에서 한다.

2단계 — Actions 항목 열기

"구성" 탭 하단으로 스크롤하면 "작업 만들기" 또는 "Actions" 버튼이 있다. 클릭하면 Actions 편집 화면이 열린다. 여기서 인증 방식과 스키마를 입력하게 된다.

3단계 — OpenAPI 스키마 입력

스키마 입력 칸에 연결할 API의 명세를 JSON 또는 YAML 형식으로 붙여넣는다. 스키마를 입력하면 화면 아래에 "감지된 작업" 목록이 자동으로 표시된다. 이 목록에 원하는 엔드포인트가 잘 인식됐는지 확인하면 된다.

4단계 — 테스트 및 저장

오른쪽 미리보기 패널에서 바로 테스트가 가능하다. GPT와 대화를 나눠보면서 API가 제대로 호출되는지, 응답이 올바르게 표시되는지 확인한다. 문제가 없으면 저장하고, 공개 범위(나만, 링크 공유, 공개)를 설정하면 완성이다.

사용 조건은 ChatGPT Plus 이상의 유료 플랜이 필요하다. 무료 계정으로는 Custom GPT를 만들 수 있지만, Actions를 포함한 GPT를 제대로 활용하려면 유료 플랜이 현실적으로 필요하다.

---

OpenAPI 스키마 작성 — 처음엔 복잡해 보이지만

GPTs Actions에서 가장 낯선 부분이 바로 OpenAPI 스키마다. OpenAPI 스키마는 "이 API가 어떻게 생겼는지"를 표준 형식으로 정리한 문서다. GPT는 이 문서를 읽고 어떤 API가 있고, 어떤 파라미터가 필요하고, 어떤 결과가 돌아오는지 파악한다.

처음 보면 복잡해 보이지만, 구조 자체는 단순하다. 실제로 간단한 날씨 API를 연결하는 스키마 예시를 보면 이해가 빠르다.

openapi: "3.1.0"
info:
  title: 날씨 API
  version: "1.0"
servers:
  - url: https://api.weatherexample.com
paths:
  /current:
    get:
      operationId: getCurrentWeather
      summary: 현재 날씨 조회
      parameters:
        - name: city
          in: query
          required: true
          schema:
            type: string
          description: 도시 이름 (예: Seoul)
      responses:
        "200":
          description: 날씨 정보 반환

이 스키마가 하는 일은 간단하다. "https://api.weatherexample.com/current 엔드포인트에 city 파라미터를 GET 방식으로 보내면 날씨 정보를 받아온다"는 것을 GPT에게 알려주는 것이다. 스키마를 붙여넣으면 GPT가 사용자가 "서울 날씨 알려줘"라고 했을 때 알아서 city=Seoul을 파라미터로 채워 API를 호출한다.

주의할 점 몇 가지가 있다.

• operationId는 각 엔드포인트마다 고유해야 한다. GPT가 어떤 기능인지 식별하는 ID다.
• summary와 description을 꼼꼼하게 써줄수록 GPT가 적절한 상황에 API를 호출한다. "이 기능이 무엇을 하는지"를 GPT가 이해해야 하기 때문이다.
• 처음 스키마를 직접 작성하기 어렵다면, OpenAI가 만든 Actions GPT를 활용하면 도움이 된다. API 문서를 넣어주면 스키마 초안을 잡아준다.

스키마 형식은 OpenAPI 3.1.0을 기준으로 작성하는 것이 권장된다. 구형 형식(2.0)도 인식은 되지만, 최신 기능 지원이나 안정성 면에서 3.1.0이 낫다.

---

인증 방식 세 가지 — None, API Key, OAuth

Actions 편집 화면에서 스키마 바로 위에 인증(Authentication) 설정이 있다. 연결하려는 API가 어떤 방식으로 접근을 허용하는지에 따라 선택이 달라진다.

None — 인증 없음

공개 API를 사용할 때 선택한다. API 키 없이 누구나 접근할 수 있는 서비스라면 이 방식이다. 테스트 목적으로 간단한 공개 API(환율, 날씨 일부 서비스 등)를 연결할 때 가장 빠르게 시작할 수 있다.

API Key — API 키 인증

가장 많이 쓰는 방식이다. 연결할 서비스에서 발급받은 API 키를 GPT에 등록해두면, 이후 GPT가 API를 호출할 때마다 자동으로 키를 함께 보낸다. 사용자가 키를 직접 입력할 필요 없이, GPT 제작자가 미리 설정해두는 구조다.

API 키를 어떻게 전달할지는 두 가지로 나뉜다. Authorization header에 넣는 방식과 Query parameter로 URL에 붙이는 방식이다. 대부분의 서비스는 Authorization header 방식을 선택하면 된다.

주의할 점은 여기 입력한 API 키는 GPT를 사용하는 사람이 직접 볼 수는 없지만, GPT 제작자가 단일 키를 등록하는 방식이라 여러 사람이 같은 GPT를 쓰면 같은 키로 요청이 나간다는 것이다. 사용량 제한이 있는 API라면 이 부분을 고려해야 한다.

OAuth — 사용자별 로그인 인증

사용자마다 개별 로그인이 필요한 경우에 쓴다. 예를 들어 구글 캘린더나 GitHub처럼 사용자 본인의 계정 데이터에 접근해야 할 때다. 설정이 세 가지 방식 중 가장 복잡하다.

OAuth 설정에는 클라이언트 ID, 클라이언트 시크릿, Authorization URL, Token URL, 스코프(scope)가 필요하다. 연결할 서비스의 OAuth 설정 페이지에서 앱을 등록하고, OpenAI가 제공하는 리디렉트 URL(https://chatgpt.com/aip/{GPT-ID}/oauth/callback)을 등록해야 한다.

처음 API 연동을 시도하는 사람이라면 None이나 API Key 방식으로 먼저 시작해보는 게 현실적이다. OAuth는 서비스 측에서도 설정이 필요해서 진입 장벽이 높다.

---

실전에서 자주 막히는 지점과 팁

GPTs Actions를 처음 설정하면서 많이 걸리는 지점들이 있다. 미리 알고 있으면 불필요하게 헤매는 시간을 줄일 수 있다.

스키마를 넣었는데 "감지된 작업"이 없다고 나올 때

대부분 YAML/JSON 문법 오류다. 들여쓰기 한 칸 차이로 파싱이 실패한다. ChatGPT에 스키마를 붙여넣고 "OpenAPI 스키마 문법 오류 찾아줘"라고 하면 금방 잡아준다. 또는 YAML Lint 같은 온라인 검증 도구를 쓰는 게 빠르다.

API 호출은 됐는데 GPT가 엉뚱한 결과를 말할 때

스키마의 description 필드를 더 자세하게 써보자. GPT는 이 필드를 읽고 "이 API가 어떤 상황에서 쓰이는 것인지"를 판단한다. "현재 도시의 날씨를 조회합니다"보다 "사용자가 특정 도시의 날씨를 물어볼 때 호출하며, 기온과 날씨 상태를 반환합니다"처럼 구체적으로 써야 GPT가 더 잘 활용한다.

CORS 오류 또는 연결 실패

GPTs Actions는 서버 측에서 API를 호출하는 방식이라 브라우저 CORS 문제와는 무관하다. 그런데 일부 API는 OpenAI 서버의 IP를 차단하거나 특정 User-Agent를 거부하도록 설정돼 있을 수 있다. 이 경우 해당 API를 직접 연결하기 어렵고, 중간에 프록시 서버를 두는 방식을 고려해야 한다.

Actions가 있는 GPT는 모델 선택이 제한된다

앞서도 언급했지만, Actions를 포함한 GPT는 현재 GPT-4o와 GPT-4.1 모델에서만 안정적으로 동작한다. o1이나 o3 같은 추론 특화 모델에서는 Actions 기능이 제대로 작동하지 않을 수 있다. API 연동보다 추론 능력이 중요한 작업이라면 Action 없는 GPT가 더 나은 선택일 수 있다.

외부에서 공개 API를 찾아 테스트하고 싶을 때

OpenWeatherMap, CoinGecko(가상화폐 시세), REST Countries(국가 정보) 같은 서비스가 무료 API 키를 제공한다. 이런 서비스로 먼저 구조를 익히고 나중에 실제 필요한 API로 넘어가는 게 학습 순서로 좋다.

GPT 시스템 프롬프트와 Actions의 관계

시스템 프롬프트(GPT 지침)에 "언제 이 액션을 사용해야 하는지"를 추가로 적어두면 동작이 더 일관해진다. 예를 들어 "사용자가 날씨를 물어볼 때는 반드시 weather API를 호출하고 직접 날씨를 추측하지 않는다"처럼 명시해두면 GPT가 API 호출 여부를 헷갈리는 경우가 줄어든다.

---

어떤 사람한테 맞고, 어떤 사람한테는 아닌가

GPTs Actions는 분명히 유용한 기능이지만, 모든 상황에 맞는 건 아니다.

이런 사람한테 맞다:
- ChatGPT를 특정 서비스와 연결해서 반복 작업을 줄이고 싶은 사람
- 팀 내부용 AI 어시스턴트를 만들고 싶은 사람 (사내 API 연결)
- Python 코딩 없이 API 연동 자동화를 해보고 싶은 1인 개발자
- 기존 플러그인 방식으로 만든 게 있어서 Actions로 마이그레이션이 필요한 사람

이런 사람한테는 맞지 않다:
- 복잡한 로직이 필요한 경우 (조건 분기, 반복 호출, 데이터 변환 등). GPTs Actions는 단순한 API 호출에 적합하고, 복잡한 워크플로우는 n8n, Zapier, 또는 Python 코드로 구현하는 게 현실적이다.
- 실시간으로 대량 요청을 처리해야 하는 경우. GPTs Actions는 사용자와 대화 중에 트리거되는 구조라 대량 배치 처리에는 적합하지 않다.
- 무료 ChatGPT 계정 사용자. Actions 기능을 제대로 쓰려면 Plus 이상이 필요하다.

ChatGPT 플러그인이 사라지고 GPTs Actions가 그 자리를 채웠지만, 이전보다 진입 장벽이 낮아진 것도 사실이다. OpenAPI 스키마 작성이 낯설게 느껴진다면, 연결하고 싶은 API 문서를 ChatGPT에 붙여넣고 "GPTs Actions용 OpenAPI 스키마로 변환해줘"라고 해보자. 첫 번째 스키마를 직접 처음부터 쓰는 것보다 훨씬 빠르게 시작점을 잡을 수 있다.

---

Sources:
- GPT Actions — OpenAI Developers
- Getting started with GPT Actions
- GPT Action authentication | OpenAI API
- Configuring actions in GPTs | OpenAI Help Center
- GPTs Action 사용법: 외부 API 연결을 통해 차별화된 GPTs 만들기
- Have plugins been replaced completely? — OpenAI Developer Community
- ChatGPT GPTs & Plugins Guide 2026: What Actually Works Now
- Deprecations | OpenAI API
- GPT Actions — GPT와 외부 API 연동 (Wikidocs)
- ChatGPT GPTs, 이제 모델 직접 고른다! (TILNOTE)