Custom GPT 연동 방법은 대화형 인터페이스에서 외부 API를 호출하는 구성입니다. GPT Actions는 자연어를 JSON 요청으로 바꿔 조회와 앱 작업을 실행합니다. 준비물로는 OpenAPI 스키마와 인증 정보가 필요합니다.
웹앱이나 백엔드에서 모델을 직접 부를 때는 Assistants와 Chat Completions의 호출 흐름이 다릅니다. 권한과 도메인 허용, 오류 처리를 함께 점검해야 공개 링크와 스토어에서도 액션이 막히지 않습니다. 아래 순서로 개념, 액션, API 호출, 보안을 정리합니다. 콜백 URL과 개인정보 처리방침도 미리 준비합니다.
Custom GPT 연동의 기본 개념과 준비물
Custom GPT는 GPT Actions로 사용자의 질문을 REST API 호출로 바꿉니다. ChatGPT가 JSON을 만들어 3rd-party 서비스에 조회와 작업을 요청합니다. 액션 하나에는 API 인증 정보와 JSON 또는 YAML OpenAPI 스키마가 필요합니다. 이 구성이 커스텀 GPT API 연동의 출발점입니다.
스키마에는 서버 주소, 엔드포인트, 파라미터, operationId를 정의합니다. GPT 에디터에서 새 액션을 만든 뒤 스키마를 붙여넣거나 URL로 가져오거나 내장 예시로 추가합니다. Preview로 호출을 시험한 다음 권한과 도메인을 맞춥니다. 내장 예시만 쓰고 끝내면 실제 서버 경로와 어긋날 수 있으니 호스트를 반드시 고칩니다.
OpenAI 액션(Actions)으로 외부 API 연결하기
(출처: AI 강사 &컨설턴트⭐서희경)
한 GPT는 apps와 actions를 동시에 쓸 수 없습니다. 워크스페이스 도메인 허용 목록이 비어 있으면 커스텀 액션이 실행되지 않습니다. 공개 링크나 GPT Store에 올리는 GPT는 유효한 Privacy Policy URL이 있어야 합니다. GPT Actions OpenAPI 정의가 정확해야 모델이 올바른 엔드포인트를 고릅니다.
사용자는 액션 실행 전에 승인을 할 수 있습니다. 에디터에서 액션을 저장한 뒤 Preview로 요청과 응답을 확인하면 스키마 오류를 빨리 고칠 수 있습니다. 스키마의 operationId가 겹치지 않게 두고 서버 URL은 실제 호출 가능한 HTTPS 주소로 맞춥니다. 액션 이름과 설명은 사용자가 승인 화면에서 읽는 문구이므로 서비스 목적을 분명히 적습니다.
OpenAPI 스키마 작성 포인트
OpenAPI 스키마는 ChatGPT가 어떤 경로를 어떤 파라미터로 부를지 알려 주는 명세서입니다. 서버, 엔드포인트, 요청 파라미터, operationId를 빠짐없이 적습니다. JSON과 YAML 모두 사용할 수 있으며 붙여넣기와 URL import가 가능합니다. 파라미터 설명에 형식과 예시를 적으면 잘못된 값이 줄어듭니다.
필수 필드가 빠지면 Preview에서 실패하므로 응답 스키마와 오류 코드도 함께 정의합니다. 내장 예시를 복사해 대상 API 경로에 맞게 고치는 방식이 안전합니다. 경로와 메서드가 실제 서버와 다르면 액션이 4xx를 받습니다. 설명 필드에 언제 이 엔드포인트를 쓸지 적어 두면 모델이 도구를 고르기 쉽습니다.
인증 방식과 콜백 URL 설정
인증은 에디터에서 None, API Key, OAuth 중 고릅니다. API 키는 저장 시 암호화되고 서버 대 서버 호출에 맞습니다. OAuth는 사용자별 로그인이며 grant_type은 authorization_code입니다.
리다이렉트 URL은 https://chat.openai.com/aip/{g-GPT-ID}/oauth/callback 과 chatgpt.com의 같은 경로입니다. state 파라미터는 필수이며 토큰은 Authorization 헤더로 보냅니다. 액션을 부르면 ChatGPT UI에 Sign in 버튼이 나타납니다. Custom GPT 웹훅 인가와 혼동하지 말고 콜백 호스트를 문서 그대로 등록합니다.
웹앱·백엔드에서 Custom GPT API 호출하기
Custom GPT 웹훅처럼 외부에서 대화를 붙이려면 서버가 OpenAI API를 호출하는 구조가 필요합니다. 브라우저에 비밀 키를 두지 말고 백엔드에서 요청을 보냅니다. 세션과 사용자 식별자를 서버에 저장해 후속 메시지를 이어서 처리합니다. 요청 본문과 쿼리는 서버에서 검증한 뒤 업스트림으로 넘깁니다.
응답 지연과 재시도, 타임아웃을 정해 두면 프론트엔드가 멈춘 것처럼 보이지 않습니다. 로그에는 토큰과 개인정보를 남기지 마십시오. 율 제한에 걸리면 지수 백오프로 재시도하고 사용자에게 잠시 기다려 달라고 안내합니다. 호출 ID를 응답과 로그에 같이 남겨 고객 문의와 서버 로그를 맞출 수 있습니다.
Assistants·Chat Completions 연동 차이
Assistants API는 스레드에 메시지를 쌓고 도구와 파일을 붙이기 쉬운 편입니다. Chat Completions는 매 요청에 대화 이력을 직접 넣어 호출합니다. 어시스턴트 API 호출은 상태 있는 업무에 맞고 Completions는 짧은 왕복에 맞습니다.
두 방식 모두 서버에서 API 키를 보관해야 하며 모델과 온도, 최대 토큰을 환경별로 나눕니다. 커스텀 GPT API 연동을 앱에 넣을 때는 사용자 입력 검증을 먼저 하십시오. 스트리밍이 필요하면 응답 청크를 프론트엔드로 그대로 전달하지 말고 서버에서 잘라 보냅니다. 도구 호출 결과는 스레드에 다시 넣어 다음 답변을 만듭니다.
권한·보안·오류 처리 체크리스트
공개 GPT의 액션은 Privacy Policy URL이 유효해야 합니다. 워크스페이스 허용 도메인에 API 호스트를 넣지 않으면 호출이 막힙니다. API 키는 에디터에만 두고 프론트엔드에 노출하지 마십시오. 액션 실패 시 재시도 횟수와 대기 시간을 서버 정책으로 고정합니다.
OAuth 토큰은 Authorization 헤더로만 보내고 로그에 남기지 않습니다. 4xx는 스키마와 권한을, 5xx는 서버 상태를 먼저 확인합니다. 사용자에게는 원인 코드 대신 다음에 할 조치를 안내합니다. CORS를 넓게 열지 말고 허용 오리진을 서비스 도메인으로 제한합니다.
| 점검 항목 | 확인 기준 |
|---|---|
| 인증 | None, API Key, OAuth 중 선택하고 키는 암호화 저장 |
| 도메인 | 워크스페이스 허용 목록에 API 호스트 등록 |
| OAuth 콜백 | chat.openai.com과 chatgpt.com 경로, state 필수 |
| 공개 배포 | 유효한 Privacy Policy URL과 실행 전 승인 |
실무 적용 후 정리와 다음 단계
스키마와 인증, 도메인 허용을 맞춘 뒤 Preview로 액션을 검증하면 GPT 외부 서비스 연결이 안정적으로 동작합니다. 웹앱은 백엔드에서 Assistants 또는 Completions를 부르고 키를 숨깁니다. 공개 배포 전에는 개인정보 처리방침과 사용자 승인을 다시 확인합니다.
다음 단계로는 오류 코드별 안내 문구와 재시도 규칙을 문서화하는 일이 남습니다. 운영 중에는 허용 도메인과 콜백 URL이 바뀌지 않았는지 주기적으로 점검하십시오. 모니터링 지표에는 액션 성공률과 평균 지연을 넣고 임계값을 넘으면 알림을 켭니다. 스키마 버전이 바뀌면 Preview를 다시 돌린 뒤 배포합니다.
