샌드박스에서 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 액세스 토큰으로 바꾼 다음,
샌드박스 사용자 인증 정보를 로드하세요.
샌드박스에서 Codex CLI 실행하기
cws-agent를 사용해 샌드박스를 시작하고 터미널을 연결하세요. Codex TUI와
에이전트 프로세스는 모두 샌드박스 안에서 실행됩니다.
-
cws-agent설치 안내를 따르세요. API 키로 인증하려면 시작하기 전에 로컬에서OPENAI_API_KEY를 export하세요. 이 도구는 해당 키를 샌드박스에 전달한 뒤 Codex의 로그인 명령어로 저장합니다. -
[SANDBOX-NAME]을 영문 소문자, 숫자, 하이픈으로 구성된 1~40자의 이름으로 바꾸세요. 이름은 영문자 또는 숫자로 시작해야 합니다.[REPOSITORY-URL]은 공개 저장소 URL로 바꾸세요.스킬 또는 Model Context Protocol(MCP) 임포트 프롬프트가 나타나면, 이 예제에서는 Enter 키를 눌러 건너뛰세요. Codex가 샌드박스의 프로젝트 디렉터리에서 열립니다. 이어서 표시되는 워크스페이스 신뢰 및 인증 프롬프트에 따라 진행하세요.--permission-mode native를 지정하면 Codex 자체의 권한 설정이 유지됩니다. 지정하지 않으면 래퍼는 기본적으로 승인 프롬프트를 건너뜁니다. 자세한 내용은cws-agent권한 모드를 참조하세요. -
계정 로그인이 필요하면 TUI를 종료한 다음 샌드박스에서 인증하세요.
Codex에 표시되는 로그인 절차를 따르세요. 헤드리스 기기 로그인 및 워크스페이스 제한 사항은 Codex 인증을 참조하세요.
-
세션 확인을 진행하세요. 샌드박스가 실행 중일 때 나중에
다시 연결하려면 같은
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 샌드박스 생성
다음 내용을create_codex_ssh.py 파일에 저장하세요. 이 스크립트는 8시간 동안 유지되는 샌드박스를 생성하고,
Codex 0.154.0을 설치한 다음, 공개 키 SSH 인증을 사용하는 비루트(non-root) agent 계정을
설정합니다. OpenAI 키는 표준 입력(stdin)을 통해 codex login에 전달되며,
샌드박스 생성 설정에는 저장되지 않습니다. Codex는 로그인 정보를
샌드박스 내부에 저장합니다.
또한 이 스크립트는 유효 기간이 1일인 TLS 인증서를 생성하고, 인증된 Sandboxes SDK를 통해 공개
인증서와 SSH 호스트 키를 조회합니다. 생성된
클라이언트 설정은 이 둘을 모두 검증합니다. 나중에 다시 연결하려면 출력 디렉터리를 삭제하지 말고 보관하세요.
[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 이상입니다.-
샌드박스의 프로젝트 디렉터리에서 앱 서버를 시작합니다. 이 명령어는 앱 서버가 종료되더라도 시작
출력을 저장합니다. 터미널은 열어 두세요.
-t옵션은 원격 터미널을 할당하므로 Ctrl+C 입력이 리스너에 전달됩니다. -
두 번째 터미널에서 로컬 포트를 해당 리스너로 포워딩하고
연결을 유지하세요.
-
세 번째 터미널에서 로컬 TUI를 연결하고 원격
프로젝트 디렉터리를 명시적으로 선택하세요.
-
TUI에
/workspace/project가 표시되는지 확인한 다음 세션 확인을 완료하세요. 연결에 실패하면 보존된 시작 출력을 확인하세요.
codex --remote 명령어를 사용하세요.
이 리스너는 데스크톱 앱이 관리하는 앱 서버와 별개입니다.
두 환경 간에 대화를 공유할 수 있는지는 검증되지 않았습니다. 자세한 내용은 OpenAI의
로컬 TUI 연결 레퍼런스를 참조하세요.
작업을 마치면 TUI를 종료한 다음, 리스너 터미널과
포워딩 터미널에서 각각 Ctrl+C를 누르세요.
SSH 샌드박스 재연결 및 중지의
절차에 따라 파일을 조회하고 컴퓨팅을 중지하세요.
데스크톱 및 모바일 앱 사용
먼저 SSH로 액세스할 수 있는 샌드박스 만들기를 완료하세요. 데스크톱 앱에서 샌드박스를 SSH 프로젝트로 추가한 다음, Remote를 사용해 페어링된 휴대폰에서 작업을 이어서 진행하세요. SSH 연결은 데스크톱 호스트가 유지합니다.데스크톱 앱 연결하기
샌드박스를 원격 프로젝트로 추가한 다음, Codex가 샌드박스의 파일 시스템에 파일을 쓰는지 확인하세요.-
~/.ssh/cw-codex-session/ssh_config파일에서 생성된Host cw-codex블록을 복사합니다. 복사한 블록을~/.ssh/config파일의Host *기본값보다 앞에 붙여 넣습니다. 기존Host cw-codex항목이 있으면 중복으로 추가하지 말고 교체하세요. -
ssh cw-codex 'codex --version'을 실행합니다. 인증 오류나 호스트 키 오류가 발생하면 다음 단계로 넘어가기 전에 해결하세요. -
데스크톱 앱에서 Settings > Connections를 연 다음,
cw-codexSSH 호스트를 추가하거나 활성화합니다. -
원격 프로젝트 폴더로
/workspace/project를 선택하고 프로젝트를 저장합니다. -
해당 원격 프로젝트를 열고 대화를 시작합니다. 민감하지 않은 고유한 값을
/workspace/project/sandbox-proof.txt파일에 쓰도록 Codex에게 요청하세요. -
터미널에서 결과를 직접 확인합니다.
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에서
다음 프롬프트를 보내세요.
- cws-agent
- SSH를 통한 로컬 CLI
SSH 샌드박스에 다시 연결하고 중지하기
샌드박스가 실행 중일 때는 동일한cw-codex 호스트와 프로젝트를 사용하세요.
SSH 연결을 끊거나 데스크톱 앱을 닫아도 샌드박스 컴퓨팅은 중지되지 않습니다.
샌드박스를 중지하기 전에 작업 내용을 Git에 저장하거나 필요한 파일을 복사하세요.
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가 활성화되지 않습니다.