Skip to main content
CoreWeave 샌드박스에 있는 저장소를 대상으로 Codex를 실행하세요. 샌드박스 안에서 Codex 명령줄 인터페이스(CLI)를 실행하거나, 로컬 CLI를 Codex 앱 서버에 연결하거나, 원격 프로젝트에서 데스크톱 및 모바일 앱을 사용할 수 있습니다. 세 가지 방법 모두 에이전트 프로세스, 워크스페이스, 명령어 실행은 샌드박스 안에서 처리됩니다. 이 예시에서는 모델 요청에 OpenAI를 사용합니다.

샌드박스에서 Codex를 실행하는 방법 선택

앱 서버는 원격 CLI 및 데스크톱 연결을 위한 에이전트 백엔드입니다. 에이전트와 상호작용할 위치를 선택하세요. 연결된 CLI는 cws-agent를 사용해 샌드박스를 생성합니다. 로컬 CLI와 데스크톱 앱은 동일한 SSH 샌드박스 설정을 사용합니다. 모바일에서 액세스하려면 Remote를 통해 휴대폰을 데스크톱 호스트와 페어링하세요. 휴대폰은 해당 호스트에 연결되고, 호스트는 SSH를 통해 샌드박스에 연결됩니다. 데스크톱 호스트는 절전 모드로 전환되지 않도록 하고, 온라인 상태에서 앱이 계속 실행되도록 유지하세요. 자세한 내용은 Remote를 통한 모바일 및 다른 데스크톱 연결을 참조하세요. 로컬 터미널 사용자 인터페이스(TUI)는 입력을 전송하고, 출력을 표시하며, 승인을 처리합니다. 원격 에이전트 세션은 앱 서버가 관리하며, 노트북에서 실행되는 에이전트의 개별 명령어를 전달하는 방식이 아닙니다. 자세한 내용은 OpenAI 앱 서버 가이드를 참조하세요. 앱 서버를 시작해도 해당 세션이 데스크톱 또는 모바일 앱에 등록되지는 않습니다. 이러한 인터페이스는 데스크톱 및 모바일 앱 사용에 설명된 별도의 연결 설정을 사용합니다. OpenAI의 Remote 문서에는 이 자체 호스팅 세션을 웹사이트에 연결하는 플로우가 정의되어 있지 않습니다. 브라우저 액세스는 이 가이드에서 다루지 않습니다. 프로그래밍 방식의 Agents API 워크플로는 별도의 실행 모델을 사용합니다. 자세한 내용은 OpenAI Agents API 레시피를 참조하세요.

사전 요구 사항

시작하기 전에 다음 항목을 준비하세요.
  • SANDBOX_USER 액션이 부여된 CoreWeave API 액세스 토큰. CPU 샌드박스에 사용할 용량도 필요합니다.
  • Codex를 지원하는 OpenAI 계정 또는 OpenAI API 키. 이 가이드의 앱 서버 예시는 API 키 인증과 API 결제를 사용합니다.
  • 공개 저장소 URL. 비공개 저장소를 복제하려면 샌드박스에 Git 사용자 인증 정보가 있어야 합니다.
  • OpenAI, 패키지 레지스트리, Git 호스트에 대한 아웃바운드 연결
로컬 터미널에서 [API-ACCESS-TOKEN]을 CoreWeave API 액세스 토큰으로 바꾼 다음, 샌드박스 사용자 인증 정보를 로드하세요.
샌드박스 생성 예시에서는 최대 수명을 실제 경과 시간 기준 8시간으로 설정하며, 이는 비활성 타이머가 아닙니다. 작업을 마치면 샌드박스를 중지하세요. 모델 사용과 샌드박스 컴퓨팅에는 요금이 각각 별도로 부과될 수 있습니다.

샌드박스에서 Codex CLI 실행하기

cws-agent를 사용해 샌드박스를 시작하고 터미널을 연결하세요. Codex TUI와 에이전트 프로세스는 모두 샌드박스 안에서 실행됩니다.
  1. cws-agent 설치 안내를 따르세요. API 키로 인증하려면 시작하기 전에 로컬에서 OPENAI_API_KEY를 export하세요. 이 도구는 해당 키를 샌드박스에 전달한 뒤 Codex의 로그인 명령어로 저장합니다.
  2. [SANDBOX-NAME]을 영문 소문자, 숫자, 하이픈으로 구성된 1~40자의 이름으로 바꾸세요. 이름은 영문자 또는 숫자로 시작해야 합니다. [REPOSITORY-URL]은 공개 저장소 URL로 바꾸세요.
    스킬 또는 Model Context Protocol(MCP) 임포트 프롬프트가 나타나면, 이 예제에서는 Enter 키를 눌러 건너뛰세요. Codex가 샌드박스의 프로젝트 디렉터리에서 열립니다. 이어서 표시되는 워크스페이스 신뢰 및 인증 프롬프트에 따라 진행하세요. --permission-mode native를 지정하면 Codex 자체의 권한 설정이 유지됩니다. 지정하지 않으면 래퍼는 기본적으로 승인 프롬프트를 건너뜁니다. 자세한 내용은 cws-agent 권한 모드를 참조하세요.
  3. 계정 로그인이 필요하면 TUI를 종료한 다음 샌드박스에서 인증하세요.
    Codex에 표시되는 로그인 절차를 따르세요. 헤드리스 기기 로그인 및 워크스페이스 제한 사항은 Codex 인증을 참조하세요.
  4. 세션 확인을 진행하세요. 샌드박스가 실행 중일 때 나중에 다시 연결하려면 같은 connect 명령어를 사용하면 됩니다. 저장된 Codex 대화를 재개하는 방법은 cws-agent 세션을 참조하세요.

SSH로 액세스할 수 있는 샌드박스 만들기

로컬 CLI와 데스크톱 앱 중 어느 쪽을 사용하든 이 설정을 완료하세요. 이 설정에서는 Sandboxes 소프트웨어 개발 키트(SDK)를 사용하여 Codex가 설치되어 있고 루트가 아닌 SSH 사용자로 인증된 샌드박스를 만듭니다. cws-agent는 필요하지 않습니다. 이 설정에서는 TLS(Transport Layer Security) 패스스루 엔드포인트와 stunnel을 사용하여 엔드포인트를 통해 SSH 트래픽을 전달합니다. 생성된 Python ProxyCommand가 TLS 인증서를 검증하면, 이어서 SSH가 사용자의 키를 인증하고 호스트 키를 검증합니다. 앱 서버에는 공개 리스너가 없습니다. 이는 OpenAI의 네트워크 노출 가이드를 따르는 방식입니다.

SSH 클라이언트 준비

Python 3.12+, uv, OpenSSH가 설치된 macOS 또는 Linux 컴퓨터를 사용하세요. 데스크톱에서 액세스하려면 OpenAI의 SSH 호스트 안내에 나와 있는 지원되는 앱과 운영 체제를 사용하세요. 이 설정에는 사전 요구 사항에서 준비한 샌드박스 사용자 인증 정보와 API 결제가 활성화된 OpenAI API 키가 필요합니다. [OPENAI-API-KEY]를 사용자의 OpenAI API 키로 바꾸세요.
생성된 SSH 설정은 이 Python 인터프리터의 절대 경로를 사용해 TLS 포워더를 실행합니다. 샌드박스를 사용하는 동안에는 Python 설치와 출력 디렉터리를 삭제하거나 옮기지 말고 사용 가능한 상태로 유지하세요. 전용 SSH 키를 생성한 다음, 실행 중인 SSH 에이전트에 로드하세요. 사용하지 않는 파일 이름을 선택하고, 프롬프트가 표시되면 암호를 입력하세요.
개인 키는 사용자의 컴퓨터에만 보관됩니다. 설정 스크립트는 공개 키만 샌드박스에 복사합니다.

SSH 샌드박스 생성

다음 내용을 create_codex_ssh.py 파일에 저장하세요. 이 스크립트는 8시간 동안 유지되는 샌드박스를 생성하고, Codex 0.154.0을 설치한 다음, 공개 키 SSH 인증을 사용하는 비루트(non-root) agent 계정을 설정합니다. OpenAI 키는 표준 입력(stdin)을 통해 codex login에 전달되며, 샌드박스 생성 설정에는 저장되지 않습니다. Codex는 로그인 정보를 샌드박스 내부에 저장합니다. 또한 이 스크립트는 유효 기간이 1일인 TLS 인증서를 생성하고, 인증된 Sandboxes SDK를 통해 공개 인증서와 SSH 호스트 키를 조회합니다. 생성된 클라이언트 설정은 이 둘을 모두 검증합니다. 나중에 다시 연결하려면 출력 디렉터리를 삭제하지 말고 보관하세요.
create_codex_ssh.py
[REPOSITORY-URL]을 공개 Git 저장소 URL로 바꾸고, 저장소 외부에 새 출력 디렉터리를 지정하세요:
설정이 완료되면 ssh_config 파일의 위치가 출력되며 샌드박스는 계속 실행 상태로 유지됩니다. 출력 디렉터리에는 sandbox-id, tls.crt, known_hosts 파일과 tls_proxy.py 포워더도 함께 생성됩니다. 샌드박스 생성 후 설정에 실패하면 스크립트가 샌드박스를 중지하려고 시도합니다. 중지에도 실패하면 수동으로 정리 작업을 할 수 있도록 원본 오류 메시지에 샌드박스 ID가 포함됩니다. Codex를 연결하기 전에 SSH 연결을 확인하세요.
출력에 agent, codex-cli 0.154.0, repository-ready가 포함되어야 합니다. 첫 연결에 실패하면 엔드포인트와 서비스가 완전히 시작될 때까지 기다린 후 재시도하세요. 연결이 계속 실패하면 Sandboxes SDK를 통해 /var/log/codex-sshd.log 및 /var/log/codex-stunnel.log 파일을 확인하세요. SSH 연결을 확인했으면 로컬 CLI 또는 데스크톱 및 모바일 앱 중 하나를 선택해 계속 진행하세요.

로컬 CLI를 Codex 앱 서버에 연결

먼저 SSH 액세스가 가능한 샌드박스 생성을 완료하세요. 지원되는 Node.js 장기 지원(LTS) 릴리스를 사용하여 동일한 Codex 버전을 로컬에 설치하세요. npm 패키지에 명시된 최소 요구 사항은 Node.js 16 이상입니다.
OpenAI는 앱 서버 WebSocket 전송을 실험적 기능으로 분류하며 프로덕션 워크로드에서는 지원하지 않습니다. 이 예제에서는 리스너와 포워딩된 포트를 루프백 주소에 바인딩하고 SSH를 통해 트래픽을 전달합니다. 해당 호스트의 다른 프로세스도 루프백 포트에 접근할 수 있으므로 신뢰할 수 있는 호스트를 사용하세요.
SSH 터널을 통해 로컬 CLI를 연결합니다.
  1. 샌드박스의 프로젝트 디렉터리에서 앱 서버를 시작합니다. 이 명령어는 앱 서버가 종료되더라도 시작 출력을 저장합니다. 터미널은 열어 두세요.
    -t 옵션은 원격 터미널을 할당하므로 Ctrl+C 입력이 리스너에 전달됩니다.
  2. 두 번째 터미널에서 로컬 포트를 해당 리스너로 포워딩하고 연결을 유지하세요.
  3. 세 번째 터미널에서 로컬 TUI를 연결하고 원격 프로젝트 디렉터리를 명시적으로 선택하세요.
  4. TUI에 /workspace/project가 표시되는지 확인한 다음 세션 확인을 완료하세요. 연결에 실패하면 보존된 시작 출력을 확인하세요.
리스너가 실행 중일 때 저장된 대화를 이어서 진행하려면 SSH 터널을 다시 연결한 다음 원격 세션 선택기를 여세요.
재개할 대화를 선택하세요. 새 대화를 시작하려면 대신 원래의 codex --remote 명령어를 사용하세요. 이 리스너는 데스크톱 앱이 관리하는 앱 서버와 별개입니다. 두 환경 간에 대화를 공유할 수 있는지는 검증되지 않았습니다. 자세한 내용은 OpenAI의 로컬 TUI 연결 레퍼런스를 참조하세요. 작업을 마치면 TUI를 종료한 다음, 리스너 터미널과 포워딩 터미널에서 각각 Ctrl+C를 누르세요. SSH 샌드박스 재연결 및 중지의 절차에 따라 파일을 조회하고 컴퓨팅을 중지하세요.

데스크톱 및 모바일 앱 사용

먼저 SSH로 액세스할 수 있는 샌드박스 만들기를 완료하세요. 데스크톱 앱에서 샌드박스를 SSH 프로젝트로 추가한 다음, Remote를 사용해 페어링된 휴대폰에서 작업을 이어서 진행하세요. SSH 연결은 데스크톱 호스트가 유지합니다.

데스크톱 앱 연결하기

샌드박스를 원격 프로젝트로 추가한 다음, Codex가 샌드박스의 파일 시스템에 파일을 쓰는지 확인하세요.
  1. ~/.ssh/cw-codex-session/ssh_config 파일에서 생성된 Host cw-codex 블록을 복사합니다. 복사한 블록을 ~/.ssh/config 파일의 Host * 기본값보다 앞에 붙여 넣습니다. 기존 Host cw-codex 항목이 있으면 중복으로 추가하지 말고 교체하세요.
  2. ssh cw-codex 'codex --version'을 실행합니다. 인증 오류나 호스트 키 오류가 발생하면 다음 단계로 넘어가기 전에 해결하세요.
  3. 데스크톱 앱에서 Settings > Connections를 연 다음, cw-codex SSH 호스트를 추가하거나 활성화합니다.
  4. 원격 프로젝트 폴더로 /workspace/project를 선택하고 프로젝트를 저장합니다.
  5. 해당 원격 프로젝트를 열고 대화를 시작합니다. 민감하지 않은 고유한 값을 /workspace/project/sandbox-proof.txt 파일에 쓰도록 Codex에게 요청하세요.
  6. 터미널에서 결과를 직접 확인합니다.
파일 내용이 요청한 값과 일치하면 정상입니다. 데스크톱 앱은 SSH 사용자의 로그인 셸로 원격 앱 서버를 시작합니다. 따라서 해당 사용자 계정에 Codex가 설치되어 있고 인증도 완료되어 있어야 합니다. 자세한 내용은 OpenAI의 데스크톱 SSH 설정을 참조하세요.

Remote를 통한 모바일 및 다른 데스크톱 연결

OpenAI의 Remote 기능은 페어링된 호스트를 통해 지원되는 데스크톱 앱과 모바일 앱을 연결합니다. 공식 문서에 안내된 모바일 설정은 Mac 또는 Windows 호스트의 ChatGPT 데스크톱 앱에서 시작하며, 두 기기 모두 동일한 계정과 워크스페이스를 사용해야 합니다. 조직 설정 및 롤아웃 가용성에 따라 액세스가 제한될 수 있습니다. 휴대폰에서 샌드박스 작업을 하려면 먼저 해당 데스크톱 호스트를 샌드박스의 SSH 프로젝트에 연결한 다음, 휴대폰을 데스크톱 호스트와 페어링하세요. iOS 또는 Android용 ChatGPT에서 Remote를 사용하면 휴대폰이 데스크톱 호스트에 연결되고, 데스크톱 호스트가 샌드박스에 연결됩니다. 데스크톱 앱은 절전 모드로 전환되지 않은 상태로 계속 실행되고 온라인 상태를 유지해야 합니다. Control other devices를 사용할 수 있는 경우 지원되는 다른 Mac 또는 Windows 데스크톱 앱도 동일한 호스트에 연결할 수 있습니다. OpenAI의 Remote 설정 안내를 따르세요. 앱 서버 WebSocket URL은 모바일 페어링 URL이 아닙니다. 또한 Agents API의 codex exec-server --remote 연결로는 모바일 기기를 페어링할 수 없습니다.

세션 연속성 및 기타 진입점

Remote는 페어링된 기기에서 연결된 호스트의 채팅을 이어서 진행하는 기능을 지원합니다. 하지만 그렇다고 해서 직접 실행한 codex --remote 예시로 시작한 대화가 별도로 설정한 데스크톱 SSH 프로젝트에도 표시된다는 의미는 아닙니다. 이 설정에서는 이러한 인터페이스 간 세션 인계가 검증되지 않은 것으로 간주하세요. 공개된 Remote 설정 문서에는 모바일 클라이언트와 지원되는 데스크톱 클라이언트가 나와 있습니다. ChatGPT 또는 Codex 웹사이트를 이 샌드박스 세션에 연결하는 방법은 문서화되어 있지 않습니다. 웹사이트를 통한 액세스는 이 가이드에서 다루는 인터페이스 범위에 포함되지 않습니다. 일부 Codex 빌드에는 실험적인 codex remote-control start 및 codex remote-control pair 명령어가 포함되어 있습니다. 이 명령어는 앱 서버 데몬과 페어링을 관리하지만, 공개된 모바일 안내에서는 헤드리스 Linux 샌드박스의 페어링 플로우를 지원한다고 명시하지 않습니다. 따라서 이 가이드에서는 이 명령어를 Claude Remote Control에 해당하는 검증된 기능으로 보지 않습니다. 이 명령어를 사용하기 전에 설치된 CLI의 도움말과 최신 OpenAI 안내를 확인하세요.

세션 확인

샌드박스에서 Codex CLI 실행 또는 로컬 CLI를 Codex 앱 서버에 연결을 진행한 경우, Codex가 샌드박스의 파일 시스템에 파일을 쓰는지 확인하세요. 데스크톱에서 액세스하려면 데스크톱 앱 연결의 안내를 따르세요. [PROOF-VALUE]를 시크릿이 아닌 고유한 값으로 바꾼 다음, 연결된 Codex TUI에서 다음 프롬프트를 보내세요.
메시지가 표시되면 쓰기를 승인하세요. TUI를 종료한 다음, 사용 중인 설정에 맞는 명령어로 로컬 터미널에서 파일을 직접 확인하세요.
값이 일치하면 에이전트가 이 샌드박스의 파일 시스템에 파일을 썼음을 확인할 수 있습니다. 단, 이것만으로는 모바일 페어링이나 다른 앱에서의 액세스까지 입증되지는 않습니다.

SSH 샌드박스에 다시 연결하고 중지하기

샌드박스가 실행 중일 때는 동일한 cw-codex 호스트와 프로젝트를 사용하세요. SSH 연결을 끊거나 데스크톱 앱을 닫아도 샌드박스 컴퓨팅은 중지되지 않습니다. 샌드박스를 중지하기 전에 작업 내용을 Git에 저장하거나 필요한 파일을 복사하세요.
저장해 둔 ID로 샌드박스를 중지하세요.
이 예제에는 퍼시스턴트 볼륨이나 스냅샷이 없습니다. 샌드박스를 중지하거나 샌드박스가 만료되면 해당 샌드박스의 파일, 로그인 상태, 엔드포인트에 더 이상 액세스할 수 없습니다. 다시 시작하려면 새 샌드박스와 출력 디렉터리를 만든 다음, Host cw-codex 블록을 새 설정으로 교체하세요. 샌드박스마다 엔드포인트, TLS 인증서, SSH 호스트 키가 새로 발급됩니다.

결과 보존 및 중지

로컬 CLI 및 데스크톱 앱에서는 SSH 샌드박스 재연결 및 중지의 안내를 따르세요. cws-agent에서는 워크스페이스 스냅샷을 저장한 후 컴퓨팅을 중지하세요.
스냅샷 생성에 실패하면 재시도하기 전에 보고된 오류를 확인하세요. 저장하지 않고 중지하려면 cws-agent down [SANDBOX-NAME] --no-snapshot을 사용하세요. TUI를 종료해도 컴퓨팅은 중지되지 않습니다. 샌드박스를 중지하거나 샌드박스가 만료되면 샌드박스의 프로세스가 종료됩니다. 컴퓨팅을 다시 시작하려면 저장해 둔 파일을 복원한 다음 Codex를 다시 시작하세요. 스냅샷은 실행 중인 프로세스를 보존하지 않습니다. 보존할 항목을 선택할 때는 저장된 Codex 인증 파일과 세션 파일을 민감한 정보로 취급하세요.

문제 해결

다음 항목을 확인하여 일반적인 문제를 해결하세요.
  • 인증이 실패하는 경우: 샌드박스 프로비저닝 사용자 인증 정보, Codex 모델 인증, SSH 키를 구분하세요. 각각 용도가 다릅니다.
  • 앱 서버 플래그가 거부되는 경우: 로컬과 샌드박스의 codex --version 출력을 비교하세요. 로컬 CLI 예시를 실행하려면 문서에 명시된 WebSocket 플래그가 필요합니다.
  • TUI는 연결되지만 작업이 실패하는 경우: 모델 액세스, 결제, 워크스페이스 신뢰, 승인 설정을 점검하세요. 전송 연결이 되었다고 해서 모델 액세스 권한이 있다는 의미는 아닙니다.
  • 연결이 끊기는 경우: 샌드박스가 실행 중일 때 다시 연결하세요. 엔드포인트 또는 전송 timeout이 발생해도 샌드박스의 수명은 연장되지 않으며, 진행 중이던 턴이 완료되었다는 보장도 없습니다.
  • 모바일 앱에서 Remote를 사용할 수 없는 경우: OpenAI의 계정, 워크스페이스, 호스트, 롤아웃 요구 사항을 확인하세요. 앱 서버를 시작하는 것만으로는 Remote가 활성화되지 않습니다.
마지막 수정일 2026년 10월 15일