Custom GPT에서 Actions를 켜면 사용자가 말로 요청한 작업을 외부 REST API 호출로 바꿉니다. ChatGPT는 그 요청을 API JSON 스키마가 요구하는 인자 형태로 만듭니다. 이 글은 Actions 연동 방법을 인증 설정부터 호출 검증까지 편집기 화면과 서버 점검 순서대로 정리합니다.
액션은 인증 방식과 OpenAPI 스키마 두 부분으로 정의됩니다. GPT 편집기에 스키마를 넣으면 서버 주소와 엔드포인트가 인식 목록으로 나타납니다. 한 GPT는 앱과 액션을 동시에 쓰지 못하므로 연동을 시작하기 전에 어떤 구성을 쓸지 먼저 고릅니다. 앱을 쓰는 GPT라면 액션 메뉴를 열기 전에 앱부터 해제합니다.
Actions 연동 방법 서론에서 검색자가 실제로 확인하고 싶어 하는.
Actions 연동이 필요한 이유와 기본 개념
GPT Actions는 Custom GPT 안에서 자연어 요청을 외부 REST API 호출로 바꿉니다. OpenAI는 사용자 말을 함수 호출에 필요한 JSON 스키마 값으로 바꾼 뒤 지정한 REST 엔드포인트를 호출한다고 도움말에서 설명합니다. 사용자는 경로 이름이나 HTTP 메서드를 몰라도 원하는 작업을 말하면 됩니다. 이 구조가 AI 액션 연결을 선택하는 이유입니다.
액션 정의는 인증 설정과 스키마 문서로 나뉩니다. 스키마에는 서버, 엔드포인트, 파라미터, operation ID가 빠짐없이 들어가야 호출이 연결됩니다. 형식은 JSON 또는 YAML 중 GPT 편집기가 검증 오류 없이 읽을 수 있는 쪽으로 준비하면 됩니다. API를 붙이는 일이 목표면 앱을 끄고 액션만 남기십시오.
Actions 연동 방법 Actions.
Actions 연동 준비와 단계별 설정 방법
(출처: InfoGrab)
GPT 편집기에서 Actions 메뉴로 들어가 Create new action을 고릅니다. OpenAPI 스키마를 붙여 넣거나 가져오기 파일로 올리면 편집기가 서버와 경로를 검사합니다. 스키마가 잘못되면 검증 오류가 바로 뜨고 맞으면 감지된 액션 이름이 목록에 뜹니다. 여기서 Actions API 연동의 호출 목록이 고정됩니다.
서버 URL, HTTP 메서드, 경로, 파라미터, operation ID를 스키마에 빠짐없이 적습니다. 웹훅 설정이 필요한 API라면 콜백 경로를 스키마 설명과 서버 구성에 같이 넣습니다. 인증 방식을 고르지 않은 채 저장하면 미리보기 호출이 거절됩니다. 저장 전에 감지 목록의 메서드와 경로가 의도한 계약과 같은지 다시 확인합니다.
Actions 연동 방법 Actions 연동 준비와 단계별 설정 방법에서.
인증·권한 설정 확인
편집기 인증은 None, API Key, OAuth 세 가지입니다. API Key는 서버 간 접근에 쓰고 OAuth는 사용자 계정마다 권한을 받습니다. 키가 필요한 API에 None을 두면 첫 호출부터 실패합니다. 키 위치는 헤더 이름 또는 쿼리 키로 서버가 정한 규약에 맞춰 지정합니다.
OAuth에는 클라이언트 ID, 시크릿, 인가 URL, 토큰 URL, 스코프가 필요합니다. 인증 토큰 발급 설정이 끝나면 ChatGPT가 콜백 URL을 보여 줍니다. 그 주소를 로그인 서버에 등록해야 인가 코드가 브라우저에서 돌아옵니다. 콜백 호스트는 chat.openai.com과 chatgpt.com을 모두 등록하고 경로는 /aip/{g-YOUR-GPT-ID}/oauth/callback 형태를 따릅니다.
| 인증 방식 | 쓰는 경우 | GPT가 보내는 값 |
|---|---|---|
| None | 공개 API | 인증 헤더 없음 |
| API Key | 서버 간 접근 | 키를 헤더 또는 쿼리에 첨부 |
| OAuth | 사용자 계정 권한 | Authorization에 Bearer 또는 Basic과 토큰 |
테스트 요청으로 연결 검증하기
스키마가 통과하면 연동 테스트 방법으로 미리보기에서 실제 요청을 한 번 보냅니다. 액션이 다루는 작업을 말로 지시하고 호출 경로와 상태 코드가 스키마 계약과 같은지 확인합니다. 테스트 키는 운영 키와 반드시 분리하고 권한 범위도 좁히십시오. 실패 본문과 요청 ID도 로그에 남겨 다음 수정을 빠르게 합니다.
OAuth를 켠 뒤에는 로그인부터 토큰 수신까지 한 흐름을 끝까지 확인합니다. 이후 요청마다 ChatGPT는 Authorization 헤더에 Bearer 또는 Basic과 토큰을 붙입니다. 서버가 Bearer만 받는데 Basic이 오면 401이 바로 납니다. 토큰 만료 시각과 스코프 목록, token_type 값도 토큰 응답 JSON에서 같이 점검합니다.
연동 실패 원인과 점검 포인트
연동 실패는 스키마 검증 오류, 인증 헤더 누락, 콜백 URL 미등록, 토큰 응답 필드 누락에서 많이 납니다. 한 GPT는 앱과 액션을 동시에 쓰지 못하므로 앱이 남아 있으면 액션 메뉴가 비활성일 수 있습니다. 편집기에 표시된 검증 문구부터 고친 뒤에 저장을 다시 시도합니다. 그다음에 서버 로그의 상태 코드와 응답 본문을 같은 시각으로 맞춰 봅니다.
서버에서는 인증 헤더 이름과 경로 불일치를 먼저 봅니다. operation ID가 중복이거나 필수 파라미터가 스키마와 다르면 ChatGPT가 잘못된 JSON을 만듭니다. 재현을 위해 GPT ID와 요청 시각, 액션 operation 이름을 서버 로그에 남깁니다. 미리보기가 호출하는 베이스 URL과 운영 서버 URL이 다른지 스테이징 키가 섞였는지도 확인합니다.
응답 형식·타임아웃 오류 대응
응답 형식이 스키마와 다르면 모델이 결과를 문장으로 풀어내지 못합니다. JSON 키 이름과 타입과 최상위가 객체인지 배열인지를 스키마 정의와 같게 맞추고 오류 본문도 문서에 적은 형식으로 돌려줍니다. 빈 본문이나 HTML 오류 페이지나 text/plain 메시지는 액션 실패로 남습니다. 성공 응답이어도 스키마에 없는 필드는 모델이 쓰지 못하므로 계약에 없는 값은 빼십시오.
타임아웃은 서버 응답이 늦거나 바깥 서비스 호출이 길 때 납니다. 액션 자체는 짧게 끝나고 오래 걸리는 일은 상태 조회 엔드포인트로 나눕니다. 제한 시간을 넘기기 전에 202와 조회 URL을 먼저 주는 편이 안전합니다. 재시도 간격과 최대 횟수도 서버 쪽에서 제한해야 같은 작업이 두 번 실행되지 않습니다.
Actions 연동 실무 핵심 정리
실무 순서는 스키마 검증, 인증 선택, 미리보기 호출, 헤더와 본문 확인입니다. OAuth라면 콜백 두 주소와 토큰 응답의 access_token 필드가 빠지면 로그인이 끊깁니다. 앱과 액션을 한 GPT에 섞지 않는 규칙도 같은 단계에서 지킵니다. 이 네 가지를 배포 직전 점검 항목으로 매번 반복하면 설정 누락이 줄어듭니다.
운영 전에는 테스트 키 범위, 스코프 최소 권한, 오류 응답 형식을 다시 봅니다. 웹훅이 있으면 콜백 서명 검증도 같은 점검 목록에 넣습니다. 이 점검 순서를 지키면 Actions 연동 방법의 반복 수정 작업을 줄일 수 있습니다. 스키마나 권한이 바뀌면 기존 토큰을 폐기한 뒤 미리보기에서 한 번 더 호출해 이전 동작과 다른 회귀가 없는지 확인합니다.
