Responses API 전용
GPT-5.4 모델 기준
OpenAI Shell Tool, 써봤더니 이 조건에서만 됩니다
결론부터 말씀드리면, OpenAI Shell Tool은 Responses API에서만 동작합니다. Chat Completions API에서는 쓸 수 없고, 호스티드 컨테이너는 비활성 20분 후 데이터가 사라지며, 네트워크는 기본 차단 상태입니다. “GPT가 터미널을 직접 실행한다”는 말이 사실이긴 한데, 그 전에 넘어야 할 조건이 꽤 많습니다.
OpenAI Shell Tool이 뭔지, 정확하게 짚고 갑니다
2026년 3월 18일, OpenAI가 Responses API 업데이트를 통해 Unix Shell Tool을 정식 공개했습니다. 한마디로 GPT 모델이 직접 터미널 명령어를 실행할 수 있는 기능입니다. ls -lah, curl, grep, awk 같은 Unix 명령어를 AI가 직접 판단해서 실행하는 방식입니다.
이전까지는 Code Interpreter(코드 인터프리터)가 Python 코드를 샌드박스 안에서 실행해주는 수준이었다면, Shell Tool은 그보다 훨씬 넓은 범위의 작업을 커버합니다. 파일 시스템 탐색, 패키지 설치, 빌드 스크립트 실행, 멀티미디어 처리까지 가능합니다. (출처: OpenAI 공식 문서, platform.openai.com/docs/guides/tools-shell, 2026.03.18 기준)
💡 공식 발표문과 실제 동작 구조를 같이 놓고 보니, Shell Tool은 Code Interpreter의 “업그레이드”가 아니라 별개의 도구입니다. 두 개를 동시에 붙일 수 있고, 서로 다른 역할을 맡습니다.
Chat Completions API에선 안 됩니다 — 공식 문서 확인
가장 많이 헷갈리는 부분입니다. OpenAI 공식 문서에 딱 이렇게 나옵니다: “Shell is available through the Responses API. It’s not available via the Chat Completions API.” (출처: platform.openai.com/docs/guides/tools-shell, 2026.03.18)
기존에 gpt-5.4 모델을 Chat Completions API로 쓰고 있었다면, 그 코드 그대로는 Shell Tool을 붙일 수 없습니다. Responses API로 마이그레이션이 필요합니다. 참고로 OpenAI는 Assistants API의 종료 일정(2026년 8월 26일 예정)도 병행 발표한 상태라, Responses API 전환은 어차피 필요한 작업입니다. (출처: Microsoft Learn — Azure OpenAI, 2026.03 기준)
⚠️ Chat Completions API 사용자 주의
기존 openai.chat.completions.create() 코드에는 Shell Tool 파라미터 자체가 없습니다. client.responses.create()로 전환 후 tools=[{"type":"shell",...}] 형식으로 붙여야 합니다.
Responses API는 Chat Completions와 대화 구조가 약간 다르고, 컨텍스트 연속성 처리 방식도 다릅니다. 공식 마이그레이션 가이드(platform.openai.com/docs/guides/responses-vs-chat-completions)를 먼저 읽고 시작하는 걸 권장합니다. 생각보다 마이그레이션 자체는 간단합니다.
호스티드 컨테이너, 쓰기 전에 20분 규칙부터 알아야 합니다
Shell Tool에는 두 가지 실행 방식이 있습니다. OpenAI가 관리하는 호스티드 컨테이너를 쓰는 방식과, 직접 환경을 구성하는 로컬 셸 모드입니다. 편의상 대부분 호스티드를 먼저 씁니다. 그런데 여기서 놓치기 쉬운 규칙이 있습니다.
공식 문서에 이렇게 나옵니다: “A hosted shell container expires after 20 minutes of inactivity. When the container expires, OpenAI discards the container data and you can’t recover it.” (출처: platform.openai.com/docs/guides/tools-shell, 2026.03.18) 20분 동안 아무 요청이 없으면 컨테이너가 삭제되고, 그 안에 쓴 파일도 전부 사라집니다. 복구 방법은 없습니다.
💡 공식 문서 표현과 실제 사용 흐름을 같이 보니 이런 차이가 보였습니다. 작업 결과물은 컨테이너 내 /mnt/data에 저장되는데, 이 경로의 파일만 컨테이너 API로 다운로드가 가능합니다. 작업이 끝나면 즉시 내려받아야 하고, “나중에 꺼내면 되겠지”라고 생각했다가는 20분 안에 사라집니다.
사전 설치된 런타임은 Python 3.11, Node.js 22.16, Java 17.0, PHP 8.2, Ruby 3.1, Go 1.23입니다. (출처: platform.openai.com/docs/guides/tools-shell, 2026.03.18) 이 외 패키지가 필요하면 컨테이너 안에서 직접 설치해야 하고, 컨테이너가 만료되면 설치 환경도 사라집니다. 반복 작업이라면 컨테이너 재사용 + 패키지 재설치 자동화 스크립트를 Skills로 등록해두는 방식이 현실적입니다.
네트워크는 기본 차단 — 허용하면 생기는 보안 리스크
호스티드 컨테이너는 기본적으로 아웃바운드 네트워크가 막혀 있습니다. curl로 외부 URL을 불러오거나 pip install로 PyPI 패키지를 받으려면 org 수준 허용 목록(allow list)과 요청 수준 network_policy를 같이 설정해야 합니다. (출처: platform.openai.com/docs/guides/tools-shell, 2026.03.18)
네트워크를 열면 프롬프트 인젝션 리스크가 생깁니다. 외부에서 불러온 콘텐츠 안에 악성 지시문이 숨어 있을 수 있고, AI가 이를 그대로 실행할 위험이 있습니다. OpenAI 공식 문서도 이 점을 직접 경고합니다: “Any external content fetched over the network may contain hidden instructions intended to manipulate model behavior.” (출처: platform.openai.com/docs/guides/tools-shell, 2026.03.18) 실제로 OpenAI가 2026년 1월 5일 공식 블로그에서 프롬프트 인젝션 공격이 영구적으로 해결하기 어려운 문제일 수 있다고 인정한 배경도 여기 있습니다. (출처: gracker.ai, 2026.01.05)
| 설정 | 기본값 | 변경 방법 | 주의사항 |
|---|---|---|---|
| 아웃바운드 네트워크 | 차단 | org 허용 목록 + network_policy | 프롬프트 인젝션 리스크 |
| sudo 권한 | 불가 | 변경 불가 | 컨테이너 내 루트 권한 없음 |
| 인터랙티브 TTY | 미지원 | 변경 불가 | vi, htop 등 대화형 앱 실행 불가 |
| 컨테이너 만료 | 20분 비활성 | expires_after 파라미터 | 만료 후 데이터 복구 불가 |
Skills 기능, 편하지만 이 부분이 함정입니다
Shell Tool과 함께 공개된 Skills는 재사용 가능한 작업 번들입니다. SKILL.md라는 마크다운 파일로 작업 지시를 정의해두면, 호스티드 컨테이너에 마운트해서 반복 작업을 자동화할 수 있습니다. 파일 최대 용량은 50MB, 파일 수 제한은 500개입니다. (출처: platform.openai.com/docs/guides/tools-skills, 2026.03.18)
편리한 기능인 건 맞습니다. 그런데 OpenAI 공식 문서에서 직접 경고하는 내용이 있습니다: “Treat Skills as privileged code and instructions. Skill content can influence planning, tool usage, and command execution.” (출처: platform.openai.com/docs/guides/tools-skills, 2026.03.18) 쉽게 말해 Skills 파일 자체가 악성 지시를 담고 있으면, 모델이 그걸 그대로 실행할 수 있습니다.
💡 여러 공식 경고문을 같이 보니 이런 흐름이 보였습니다. Shell Tool의 네트워크 리스크와 Skills의 보안 리스크는 서로 연결됩니다. 네트워크를 열어 외부 Skills를 받아오는 방식을 쓰면, 두 가지 공격 경로가 동시에 열립니다. 공식 문서도 엔드유저에게 임의의 Skills를 자유롭게 선택하게 하는 제품 설계를 명시적으로 금지하고 있습니다.
또 하나 알아둘 점은, 로컬 셸 모드와 호스티드 셸의 Skills 첨부 방식이 다릅니다. 호스티드 셸은 업로드된 skill_reference를 쓰고, 로컬 셸은 로컬 파일 경로를 직접 지정합니다. 두 방식을 섞으면 실행이 안 됩니다.
Codex와 Shell Tool, 같은 것처럼 보이지만 다릅니다
OpenAI Codex(코덱스)도 터미널에서 코드를 실행합니다. 그래서 Shell Tool과 같은 기능 아니냐고 묻는 경우가 많습니다. 막상 비교해보면 둘은 설계 목적이 다릅니다.
Shell Tool은 Responses API에 붙이는 서버 사이드 에이전트 컴포넌트입니다. 개발자가 자신의 서비스 안에 AI 터미널 실행 기능을 임베드하는 용도입니다. Codex는 CLI 도구로, 개발자가 직접 쓰는 코딩 어시스턴트입니다. 공식 문서에 딱 이렇게 구분합니다: “Codex is OpenAI’s agentic coding tool… the shell tool is a primitive that gives models the ability to work inside a complete terminal environment.” (출처: platform.openai.com/docs/guides/tools-shell, 2026.03.18)
| 항목 | Shell Tool | OpenAI Codex |
|---|---|---|
| 사용 대상 | 서비스 빌더(개발자) | 코딩 작업자 직접 사용 |
| API | Responses API 전용 | CLI / Codex 앱 |
| 실행 환경 | 호스티드 컨테이너 or 로컬 | 클라우드 샌드박스 or 로컬 |
| Terminal-Bench 2.0 | — | 77.3% (GPT-5.3-Codex 기준) |
| 오픈소스 | 아니오 | Apache-2.0 (CLI) |
(표 내 벤치마크 수치 출처: morphllm.com/comparisons/codex-vs-claude-code, 2026.02.28 기준) 두 도구를 동시에 쓰는 방식도 있습니다. Codex로 빠르게 프로토타입을 만들고, Shell Tool로 서비스 내 자동화 로직을 구성하는 조합이 현실적으로 쓸 만합니다.
직접 써보니 이런 경우에 쓸 만하고, 이런 경우엔 아직입니다
솔직히 말하면, 사용 가능한 범위가 꽤 구체적입니다. 아래 상황이라면 Shell Tool이 실제로 효과가 있습니다.
- 데이터 분석 파이프라인 (CSV 처리 → Python 계산 → 결과 파일 생성)
- 멀티미디어 처리 (이미지 리사이징, 메타데이터 추출)
- 빌드 스크립트 실행 후 결과 파일 다운로드
- API 연동 테스트 (허용 도메인 설정 후)
- 반복 자동화를 Skills로 등록해두는 내부 워크플로우
- ZDR(제로 데이터 보존) 환경 — 호스티드 컨테이너 자체 사용 불가
- vi, htop 같은 대화형 TTY 앱 실행
- sudo 권한이 필요한 시스템 레벨 작업
- 컨테이너 재시작 없이 장기 세션 유지
- 엔드유저에게 임의 명령어 직접 입력 허용하는 서비스
ZDR 환경에서 Shell 실행이 꼭 필요하다면 로컬 셸 모드로 전환해야 합니다. 이 경우 인프라 관리는 전적으로 직접 해야 합니다. 공식 문서도 이 부분에 대해 별도 이유를 공개하지 않았습니다. 다만 데이터 잔존 정책 충돌이 근본 이유라는 점은 문서 구조상 명확합니다. (출처: platform.openai.com/docs/guides/tools-shell, 2026.03.18)
Q&A
마치며
OpenAI Shell Tool은 분명 강력한 기능입니다. GPT가 터미널을 직접 다루는 구조는, 단순 텍스트 생성을 넘어 실제 업무 자동화를 API 수준에서 구현하겠다는 방향성을 보여줍니다.
그런데 막상 써보면 조건이 꽤 구체적입니다. Responses API 전용이라는 점, 컨테이너 20분 만료, 네트워크 기본 차단, ZDR 환경 호환 불가 — 이 네 가지를 모르고 시작하면 예상과 다른 결과를 만납니다. 기능 자체보다 동작 조건을 먼저 파악하고 시작하는 게 더 빠릅니다.
Skills와 조합하면 반복 자동화 워크플로우를 꽤 효율적으로 구성할 수 있습니다. 다만 Skills도 보안 리스크가 있는 만큼, 신뢰할 수 있는 범위 안에서 먼저 작은 단위로 테스트해보는 방식을 권장합니다.
📎 본 포스팅 참고 자료
본 포스팅은 2026년 3월 29일 기준으로 작성되었습니다. 본 포스팅 작성 이후 서비스 정책·UI·기능이 변경될 수 있습니다. 공식 최신 정보는 platform.openai.com/docs에서 직접 확인하시기 바랍니다.
댓글 남기기