핵심 요약
- OpenAI Hosted Sandboxes 네트워크 설정은 먼저 인터넷을 차단한 상태로 설계하고, 작업에 꼭 필요한 외부 연결만 제한적으로 허용해야 합니다.
- 비공개 API, 데이터베이스, 사내 서비스까지 접근해야 한다면 샌드박스 권한을 바로 넓히기보다 통제된 게이트웨이나 자체 운영 환경을 먼저 검토하는 편이 안전합니다.
- 이 글은 코드 실행형 에이전트를 반복 작업으로 전환하려는 독립 개발자, 파일과 의존성을 다루는 AI 애플리케이션 엔지니어, 네트워크와 비밀키 경계를 관리하는 플랫폼 엔지니어를 위한 안내서입니다.
OpenAI Hosted Sandboxes 네트워크 설정은 먼저 인터넷을 차단한 상태로 설계하고, 작업에 꼭 필요한 외부 연결만 제한적으로 허용해야 합니다. 비공개 API, 데이터베이스, 사내 서비스까지 접근해야 한다면 샌드박스 권한을 바로 넓히기보다 통제된 게이트웨이나 자체 운영 환경을 먼저 검토하는 편이 안전합니다.
이 글은 코드 실행형 에이전트를 반복 작업으로 전환하려는 독립 개발자, 파일과 의존성을 다루는 AI 애플리케이션 엔지니어, 네트워크와 비밀키 경계를 관리하는 플랫폼 엔지니어를 위한 안내서입니다.
먼저 결정해야 할 것은 네트워크가 아니라 작업 범위입니다
OpenAI의 공식 안내에 따르면 Hosted Sandbox는 리눅스 작업 공간, 파일 처리, 코드 실행, 의존성 설정을 사용하는 에이전트 환경으로 설명됩니다. 실제 환경 생성 방식과 네트워크 필드는 계속 개발자 문서에서 확인해야 하며, 커뮤니티에서 언급되는 미래 기능이나 확인되지 않은 허용 목록을 현재 기능으로 간주해서는 안 됩니다. Sandbox Agent 공식 안내와 Sandbox Agents 문서를 기준으로 배포 전에 다시 확인해야 합니다.
작업을 다음처럼 나누면 선택이 빨라집니다.
| 작업 유형 | 기본 선택 | 네트워크 판단 | 피해야 할 구성 |
|---|---|---|---|
| 로컬 파일 계산과 변환 | Hosted Sandbox | 차단 유지 | 파일 처리 때문에 전체 인터넷 허용 |
| 패키지 설치와 빌드 | 제한된 외부 연결 | 승인된 저장소만 허용 | 실행 중 모델이 임의로 설치 |
| 공개 API 호출 | 제한된 외부 연결 | 대상 주소와 요청 방식 고정 | 프롬프트에 비밀키 삽입 |
| 사내 API와 데이터베이스 | 자체 운영 또는 통제된 게이트웨이 | 중계 서버에서 권한 검사 | 샌드박스에서 내부망 직접 접근 |
OpenAI Hosted Sandboxes는 기본적으로 인터넷에 접속할 수 있나요?
공식 문서가 특정 환경의 네트워크 동작을 설명하지 않는다면, 접속 가능하다고 가정해서는 안 됩니다. 애플리케이션 코드에서 실제로 DNS 조회, TLS 연결, 요청 응답이 되는지 확인하고, 성공하지 않으면 차단 상태를 기본값으로 유지하십시오. Agents SDK의 샌드박스 클라이언트 문서는 환경 생성과 연결을 구현할 때 확인할 기준을 제공하지만, 문서에 없는 보안 보장을 대신하지는 않습니다.
결정 조건
- 파일 읽기, 압축 해제, 데이터 정제만 필요하면 네트워크 차단을 선택합니다.
- 공개 패키지나 공개 API가 필요하지만 내부 자료는 다루지 않으면 승인된 외부 연결로 제한합니다.
- 사내 시스템, 데이터베이스, 결제 정보가 포함되면 자체 운영 환경 또는 통제된 중계 서버로 되돌립니다.
- 장시간 실행, 고정된 작업 공간, 세밀한 방화벽 정책이 필요하면 Hosted Sandbox를 임시 실행 환경으로만 사용하고 클라우드 작업 공간을 비교합니다.
네트워크 설정과 의존성 설치를 함께 검증하는 방법은 무엇인가요?
네트워크를 열었는데도 작업이 실패하는 경우가 많습니다. 원인은 작업 디렉터리가 비어 있거나, 시작 명령이 실행되지 않았거나, 패키지 버전이 달라졌기 때문일 수 있습니다. OpenAI Agents API의 도구 호출은 모델이 작업을 선택하는 흐름을 지원하지만, 모든 실행 전제 조건을 모델에게 맡기는 방식은 재현성이 낮습니다. Agents API 공식 소개를 참고하되, 설치와 검증은 애플리케이션 코드의 고정된 단계로 분리하십시오.
OpenAI Hosted Sandboxes에서 파이썬, 노드, 시스템 의존성은 어떻게 설치하나요?
시작 단계에서 필요한 패키지를 설치하고, 실행 중 모델이 새로운 시스템 패키지를 임의로 추가하지 못하게 하는 구성이 적합합니다. 파이썬 패키지와 노드 패키지는 잠금 파일로 버전을 고정하고, 시스템 패키지는 이미지나 시작 설정에 반영하는 편이 낫습니다. 설치가 끝났다는 메시지만 믿지 말고 실제 가져오기, 버전 확인, 작은 함수 실행까지 검증해야 합니다.
작업 디렉터리도 별도로 확인하십시오. 입력 파일이 어느 경로에 놓이는지, 결과물이 어느 경로에 저장되는지, 이전 실행의 결과가 다음 실행에 남는지를 기록해야 합니다. 임시 작업 공간과 장기 보관 공간을 같은 디렉터리로 취급하면 오래된 파일이 새 작업에 섞일 수 있습니다.
| 확인 대상 | 시작 단계에서 할 일 | 관찰할 증거 |
|---|---|---|
| 작업 디렉터리 | 입력과 출력 경로를 고정 | 경로 목록과 파일 버전 |
| 파이썬 및 노드 패키지 | 잠금 파일 기준으로 설치 | 가져오기와 버전 출력 |
| 시스템 의존성 | 이미지 또는 시작 설정에 반영 | 실행 파일 존재 여부 |
| 네트워크 | 필요한 주소만 연결 시험 | DNS, TLS, 응답 상태 |
| 산출물 | 허용된 출력 경로만 사용 | 결과 파일과 해시 기록 |
첫 단계: 가장 작은 검증 작업을 먼저 실행합니다
- 빈 작업 공간에서 입력 파일 목록을 출력합니다.
- 필요한 패키지를 가져오고 버전을 기록합니다.
- 외부 연결이 필요하면 승인된 주소 하나에만 시험 요청을 보냅니다.
- 실제 업무와 같은 파일을 작은 크기로 처리합니다.
- 결과 파일을 다시 읽어 형식과 경로를 확인합니다.
- 실패 시 명령, 표준 출력, 표준 오류, 입력 파일 버전을 함께 저장합니다.
이 과정은 네트워크가 열렸다는 추측보다 강한 증거를 제공합니다. Agents SDK 빠른 시작 문서는 에이전트와 도구를 연결하는 기본 흐름을 보여주므로, 여기에 환경 준비와 검증 단계를 명시적으로 추가하는 방식이 적합합니다.
외부 API와 사내 서비스는 왜 직접 연결하면 안 되나요?
공개 날씨 API와 사내 데이터베이스는 모두 외부 요청처럼 보이지만 위험이 다릅니다. 공개 API는 호출량과 응답 검증이 핵심이고, 사내 서비스는 네트워크 도달성보다 권한 범위와 데이터 반환 범위가 더 중요합니다. 웹훅도 수신 주소가 노출되면 임의 호출이나 중복 실행 문제가 생길 수 있습니다.
권장 구조는 에이전트가 업무용 중계 서버를 호출하고, 중계 서버가 대상 시스템과 통신하는 방식입니다. 중계 서버에서 사용자와 작업의 권한을 확인하고, 허용된 기능만 매핑하며, 필요한 필드만 반환합니다. 데이터베이스 자격 증명을 샌드박스에 넣는 대신 읽기 전용 조회 기능이나 사전 정의된 업무 명령을 제공하십시오.
에이전트 샌드박스에서 외부 API를 호출할 때는 어떻게 설정해야 하나요?
공개 API는 허용 주소, 요청 메서드, 시간 제한, 응답 크기를 제한합니다. 비공개 서비스는 주소를 열어 주는 것만으로 끝내지 말고 중계 서버와 짧은 수명의 자격 증명을 사용합니다. 모델이 읽을 수 있는 프롬프트, 파일, 명령 출력, 로그에는 API 키를 넣지 않습니다.
OpenAI Hosted Sandboxes에서 API 키가 새지 않게 하려면 어떻게 해야 하나요?
API 키를 환경 변수에 넣는 방법도 모델이 실행 결과나 오류 내용을 읽을 수 있다면 충분하지 않을 수 있습니다. 키를 샌드박스에 직접 전달하지 않고, 외부 비밀 저장소와 중계 서버에서 요청을 서명하거나 인증하도록 구성하십시오. 로그에는 키의 원문 대신 식별자와 성공 또는 실패 상태만 남깁니다. 도구 문서는 도구 경계를 설계할 때 참고할 수 있지만, 비밀키 보관을 자동으로 해결해 주는 문서로 해석해서는 안 됩니다.
주의: 작업 결과에 인증 헤더, 전체 요청 주소, 환경 변수 목록이 포함되는지 반드시 확인하십시오. 실패 로그를 편리하게 남기려다 비밀값을 장기 보관하는 실수가 자주 발생합니다.
네트워크 오류가 발생하면 어떤 순서로 확인해야 하나요?
Hosted Sandbox 네트워크 접속 실패는 어떻게 진단하나요?
먼저 환경 생성 자체가 실패했는지, 환경은 만들어졌지만 연결이 거부됐는지 나눕니다. 그다음 DNS 조회, TLS 인증, 외부 서비스 응답, 의존성 저장소 접근 순으로 확인하십시오. 에이전트가 잘못된 주소를 선택했는지와 외부 서비스가 실제로 중단됐는지도 별도로 기록해야 합니다.
- 환경 생성 실패: 현재 환경 종류, 생성 요청, 상태 이벤트를 확인합니다.
- 연결 거부: 허용된 주소와 포트, 네트워크 경계를 확인합니다.
- DNS 오류: 이름 해석 결과와 실행 시점의 주소를 기록합니다.
- TLS 오류: 인증서 검증 실패와 시스템 시간 문제를 분리합니다.
- 설치 실패: 저장소 접근, 잠금 파일, 시스템 패키지 여부를 확인합니다.
- 시간 초과: 요청 제한 시간, 외부 응답 지연, 에이전트의 반복 호출을 구분합니다.
복구 후에는 같은 입력 파일과 같은 의존성 상태로 재현하십시오. 환경 상태, 오류 이벤트, 명령 출력, 입력 파일 버전이 없으면 설정 문제와 외부 장애를 구분하기 어렵습니다. Agents SDK의 발전 안내는 실행 구조가 바뀔 수 있음을 보여주므로, 환경 필드와 인터페이스 이름을 문서와 함께 주기적으로 다시 대조해야 합니다.
어떤 작업에 Hosted Sandbox를 선택하고 언제 옮겨야 하나요?
| 업무 | 권장 환경 | 선택 이유 | 전환 신호 |
|---|---|---|---|
| 파일 정리와 데이터 변환 | Hosted Sandbox | 네트워크 없이도 검증 가능 | 장기 파일 보관이 필요함 |
| 코드 빌드와 시험 | 제한된 Hosted Sandbox | 의존성과 출력 경로를 고정 가능 | 특수 시스템 패키지와 지속 작업이 필요함 |
| 공개 웹 자료 수집 | 제한된 연결 또는 별도 수집기 | 대상 주소와 호출량을 통제 가능 | 차단 우회와 대규모 수집이 필요함 |
| 내부 업무 시스템 조작 | 통제된 게이트웨이 또는 자체 운영 | 권한과 감사 기록을 중앙 관리 | 내부망 직접 접근이 필요함 |
| 장시간 에이전트 | 클라우드 작업 공간 | 작업 공간과 복구 상태를 유지하기 쉬움 | 세션 유지와 사용자 접속이 중요함 |
완전한 네트워크 정책, 장기 작업 디렉터리, 원격 접속, 맞춤형 시스템 패키지가 필요하다면 클라우드 맥이나 원격 개발 환경이 더 적합할 수 있습니다. 반대로 일회성 파일 처리와 제한된 코드 실행은 Hosted Sandbox의 격리 경계를 유지하는 편이 관리하기 쉽습니다. 원격 환경을 검토할 때는 kvmboot 소개에서 제공 방식과 사용 범위를 먼저 확인하고, 비밀키와 네트워크 격리 기준은 별도로 문서화하십시오.
배포 전 최종 확인
- 네트워크 차단으로도 작업이 가능한지 판단했습니까?
- 허용할 외부 주소와 요청 목적을 목록으로 만들었습니까?
- 패키지와 시스템 의존성을 시작 단계에 고정했습니까?
- 비밀키가 프롬프트, 파일, 출력, 로그에 나타나지 않습니까?
- 입력과 출력 디렉터리를 분리했습니까?
- 호스트 환경이나 관련 없는 파일을 읽는 시험을 했습니까?
- 환경 상태와 실패 이벤트를 재현 가능한 형태로 기록했습니까?
- 장기 작업과 사내 시스템 접근이 필요하면 자체 운영 또는 통제된 게이트웨이를 검토했습니까?
현재 방식이 단순한 로컬 실행이나 임시 서버라면 주소와 권한이 한곳에 섞이고, 의존성 재현이 어렵고, 장기 작업 상태와 감사 로그를 따로 관리해야 하는 단점이 있습니다. 반면 kvmboot의 클라우드 작업 환경은 완전한 네트워크와 작업 공간이 필요한 경우 비교 대상이 될 수 있으므로, 도움말 센터에서 원격 접속과 운영 조건을 확인한 뒤 선택하는 편이 좋습니다. 네트워크가 제한된 단기 코드 실행은 Hosted Sandbox에 남기고, 지속적인 개발과 맞춤형 연결이 필요할 때만 클라우드 작업 공간으로 옮기는 방식이 비용과 권한을 함께 통제하기 쉽습니다.