Codex Cloud 실전 가이드: GitHub 작업을 클라우드 Agent에 맡기고 결과 검토하기

GitHub issue에 “CI의 webhook 테스트가 실패하고 있지만, 지금 로컬에서 전체 환경을 돌리기 어렵다”라고 적혀 있습니다. Codex Cloud가 클라우드 쪽 리포지토리에서 수정하도록 하고, 마지막에는 diff, 테스트 로그, PR만 받아 검토하고 싶은 상황입니다.

핵심은 “클라우드라서 더 자동화된다”가 아닙니다. Cloud task가 노트북과 분리된 깨끗하고 재현 가능한 리포지토리 환경에서 실행된다는 점입니다. 로컬 미커밋 파일, 브라우저 세션, 로컬 .env를 읽지 않습니다. 이 경계는 제약이지만 동시에 유용한 안전장치입니다.

흐름은 이렇습니다. 먼저 작업을 Cloud에 둘지 판단하고, environment를 설정하고, prompt를 쓰고, 결과를 확인한 뒤 PR을 열지, 로컬로 가져올지, @codex review를 2차 확인으로 쓸지 결정합니다.

먼저 판단하기: 이 요구를 Cloud에 둘까, 로컬에 남길까

Local, Worktree, Cloud, SSH host의 경계

Codex의 여러 진입점은 서로 다른 문제를 풉니다. 단순히 더 강하거나 약한 버전이 아닙니다.

상황	적합한 진입점	이유	주요 검증물
로컬의 작은 수정, 미커밋 파일이나 localhost에 의존	CLI / IDE / Local	로컬 작업공간, 브라우저, 로컬 서비스에 접근할 수 있음	로컬 diff, 테스트 출력
2〜3개의 독립적인 접근을 병렬로 시도	Codex app Worktree	Git 상태와 의존성 디렉터리를 분리함	worktree diff, review queue
GitHub issue, CI failure, 문서 업데이트, 재현 가능한 리포지토리 작업	Codex Cloud	원격 checkout이며, 내 PC를 떠나도 실행 가능	Cloud summary, diff, PR
PR의 2차 검토	GitHub @codex review	PR diff 기반의 표준 review를 게시함	GitHub review comments
프로젝트가 devbox나 내부 머신에 있음	Remote connection / SSH host	remote host의 파일, shell, credentials, 도구를 사용함	remote diff, terminal output

Cloud는 “더 강한 Worktree”가 아닙니다. Worktree는 여전히 내 컴퓨터에서 실행되고 Git 디렉터리만 분리합니다. Cloud는 configured cloud environment로, GitHub 리포지토리를 checkout한 뒤 원격 컨테이너 안에서 작업을 실행합니다.

Cloud에 적합한 작업에는 보통 네 가지 조건이 있습니다. 목표가 명확하고, 리포지토리 상태를 재현할 수 있고, 환경을 script로 준비할 수 있으며, Done when을 명령어나 diff로 검증할 수 있어야 합니다. CI failure 수정, 문서 보완, PR review follow-up, 특정 모듈 테스트 추가가 여기에 맞습니다.

Cloud에 넘기지 말아야 할 작업

AI assistant가 도와줄 수는 있지만, 로컬 환경을 벗어나면 안 되는 작업도 있습니다.

• 로컬 미커밋 파일에 의존: Cloud는 원격 리포지토리에서 checkout한 상태만 봅니다.
• 브라우저 세션이나 로컬 dev server에 의존: Cloud 컨테이너는 Chrome, localhost, 데스크톱 앱에 자동으로 접근하지 않습니다.
• agent phase에서 운영 secrets가 필요: secrets를 agent loop에 노출하는 설계는 피해야 합니다.
• 범위가 흐릿한 대형 refactoring: 검증 명령이 없다면 불확실성을 더 먼 곳으로 옮길 뿐입니다.
• 제품 판단이나 팀의 선택이 필요: Codex가 분석은 도울 수 있지만, 방향 전체를 직접 다시 쓰게 해서는 안 됩니다.

저라면 첫 Cloud task는 작게 잡습니다. “어떤 명령을 실행하면 완료를 알 수 있는가”를 쓸 수 없다면, 그 작업은 아직 Cloud에 넘길 준비가 되지 않았습니다.

Cloud task 전에 environment가 리포지토리를 재현하게 만들기

Cloud task의 실행 순서

Cloud task는 대체로 다음 순서로 실행됩니다.

1. 원격 container를 만듭니다.
2. 선택한 branch 또는 commit SHA를 checkout합니다.
3. setup script를 실행합니다. cached container가 복원되면 maintenance script를 실행할 수 있습니다.
4. 네트워크 정책을 적용합니다.
5. agent가 terminal command loop에서 파일을 읽고, 코드를 수정하고, 검사를 실행하고, 검증을 시도합니다.
6. answer, summary, diff를 반환합니다. 이후 follow-up을 하거나 PR을 만들 수 있습니다.

Cloud 작업이 실패하는 이유는 agent가 코드를 못 써서가 아닌 경우가 많습니다. environment가 리포지토리를 재현하지 못한 것입니다. 의존성이 설치되지 않거나, 테스트 DB가 없거나, lockfile과 runtime이 맞지 않거나, setup script가 내 노트북에만 있는 파일을 전제로 하는 식입니다.

setup script, maintenance script, cache

setup script의 역할은 컨테이너를 “막 checkout된 상태”에서 “검증 명령을 실행할 수 있는 상태”로 옮기는 것입니다. 최소 예시는 짧을 수 있습니다.

pnpm install
pnpm run typecheck
pnpm test -- --runInBand

이것은 모든 프로젝트에 통하는 템플릿이 아닙니다. Cloud environment가 의존성 설치 방법, 테스트 환경 준비 방법, 문제를 드러낼 수 있는 검사 실행 방법을 알아야 한다는 뜻입니다.

setup에 자주 들어가는 작업은 다음과 같습니다.

• 의존성, linter, formatter, typechecker, test tools 설치.
• 테스트 DB 초기화 또는 안전한 로컬 설정 대체값 생성.
• private package 설치에 필요한 일회성 인증 준비.
• 계속 유지되어야 하는 민감하지 않은 값은 script 안의 임시 export가 아니라 environment settings에 저장.

cache는 반복적인 의존성 설치 시간을 줄여 줍니다. 다만 문제를 진단할 때 확인할 층도 하나 늘어납니다. setup script, maintenance script, env vars, secrets가 바뀌면 cache는 무효화되고 새로 실행됩니다. 의존성 동작이 갑자기 달라졌다면 cache reset도 합리적인 단계입니다.

Secrets, 환경 변수, 네트워크: 오해하기 쉬운 세 가지

secrets와 environment variables의 라이프사이클

secrets와 environment variables의 가장 큰 차이는 이름이 아니라 보이는 시점입니다.

설정 항목	언제 쓰는가	넣으면 안 되는 것	검증 질문
environment variable	민감하지 않은 runtime 설정	token, private key, 운영 connection string	agent가 정말 읽어야 하는가
secret	setup 단계에서 의존성 가져오기 또는 도구 설치	agent가 직접 읽어야 하는 값	setup 후 제거되었는가
setup internet	의존성 설치, private package 가져오기	신뢰할 수 없는 script 임의 실행	lockfile이 안정적인가
agent internet access	작업이 공개 API나 문서에 접근해야 함	unrestricted 전체 인터넷	allowlist와 methods가 최소인가

secrets는 setup 단계에 어울립니다. 예를 들어 private dependency 설치나 내부 package 가져오기에 씁니다. agent phase가 시작되기 전에 제거되어야 합니다. 즉, 코드 수정 중 agent가 운영 token을 읽어야 하는 Cloud task는 설계하지 않는 편이 안전합니다.

environment variables는 task 전체에서 유지됩니다. NODE_ENV=test, 공개 API base URL, feature flag 같은 민감하지 않은 값에 적합합니다.

agent internet access는 필요할 때만 켜기

setup script는 의존성 설치를 위해 인터넷을 사용할 수 있지만, agent phase는 기본적으로 네트워크가 없습니다. 이 기본값은 중요합니다. agent가 외부 페이지나 API를 읽기 시작하면 위험도 달라지기 때문입니다.

agent internet access를 꼭 켜야 한다면 보수적으로 설정합니다.

1. 전체 인터넷을 열지 말고 구체적인 domain만 allowlist합니다.
2. 가능하면 HTTP methods를 제한합니다. 예를 들어 GET, HEAD, OPTIONS만 허용합니다.
3. agent가 민감한 파일을 읽거나, 합치거나, 외부로 upload하지 못하게 합니다.
4. 네트워크로 확인해야 하는 사실을 정확히 적어 agent가 자유 탐색하지 않게 합니다.

흔한 위험은 prompt injection, 코드나 secret 외부 유출, 악성 의존성 다운로드, license 문제입니다. 한 단계를 줄이려고 unrestricted network를 여는 것은 대개 손해입니다.

Cloud prompt는 issue처럼 쓰기

바로 실행할 수 있는 prompt 템플릿

Cloud prompt는 소원이 아니라 작은 GitHub issue처럼 보여야 합니다. 목표, 배경, 범위, 환경, 검증, 중단 조건을 넣습니다.

Goal: Fix the failing webhook.test.ts test in GitHub Actions.
Context: The failure log is below; the relevant code is probably in src/webhooks/ and tests/webhooks/.
Scope: Only fix Stripe webhook signature verification. Do not change the payment public API or refactor the test framework.
Environment: The Cloud environment has pnpm dependencies installed. Please run pnpm test tests/webhooks/webhook.test.ts first.
Done when: The target test passes; list changed files, commands you ran, checks you did not run, and risks I need to confirm manually.
Stop if: You need to add a new secret, change the database schema, modify shared/http-client.ts, or cannot reproduce the failure.

중요한 것은 형식이 아닙니다. Codex가 따를 수 있는 경계를 주는 것입니다. Cloud task가 issue에 가까울수록 검토 가능한 diff가 돌아올 가능성이 높습니다.

”조심해”보다 Stop if가 더 효과적입니다

“조심해”는 너무 추상적입니다. agent는 어디부터 선을 넘는지 알기 어렵습니다. Stop if는 위험을 구체적인 조건으로 바꿉니다.

다음처럼 쓸 수 있습니다.

• Stop if you need to add a new secret.
• Stop if you need to change the database schema.
• Stop if you must touch the shared auth middleware.
• Stop if the target test cannot be reproduced.
• Stop if the task requires broad renaming or file migration.

이렇게 쓰면 Cloud task가 고위험 지점에 닿았을 때 diff를 계속 키우기보다 멈추고 설명할 가능성이 커집니다.

Cloud task가 끝나면 summary, diff, command log 보기

언제 follow-up하고, 언제 PR을 열까

Cloud가 끝났다고 해서 “done”만 보면 안 됩니다. 먼저 네 가지를 읽습니다.

1. summary가 목표와 변경 내용을 정확히 다시 말하는가.
2. diff가 scope 안에 머무는가.
3. command log에 요청한 test, lint, typecheck가 포함되어 있는가.
4. 실행하지 못한 검사와 사람이 확인해야 할 위험이 명확히 적혀 있는가.

diff가 scope 밖 파일을 건드렸다면 먼저 물어봅니다.

The diff touches shared/http-client.ts, which was outside scope. Explain why it was necessary. If not necessary, revert that part and keep the webhook fix minimal.

대상 테스트를 실행하지 않았다면 그것도 먼저 물어봅니다.

You did not run the target test. Run pnpm test tests/webhooks/webhook.test.ts and summarize the result before opening a PR.

변경 범위가 명확하고, 검증 명령을 신뢰할 수 있으며, 남은 위험이 이름 붙여져 있을 때만 PR로 넘어갑니다.

로컬로 가져올 때 확인할 것

두 경로 모두 가능합니다.

• 작은 변경: Create PR 후 GitHub review, CI, 팀 프로세스에 맡깁니다.
• 고위험 변경: 먼저 check out locally 한 뒤 로컬 도구, Codex app review pane, IDE로 검증합니다.

로컬로 가져올 때는 최소한 다음을 봅니다.

• git status가 clean인지, 또는 독립 branch / worktree에 있는지.
• diff가 Cloud task의 목표만 포함하는지.
• 대상 test, lint, typecheck가 로컬에서도 통과하는지.
• .env*, secrets, CI config, lockfile, generated files가 변경되었는지.
• 이번 교훈을 AGENTS.md 규칙으로 남길 필요가 있는지.

Cloud diff는 merge 버튼이 아닙니다. 원격에서 실행된 한 번의 시도가 검토를 위해 돌아온 것일 뿐입니다.

GitHub의 @codex review: 2차 관문이지 merge 허가는 아닙니다

수동 트리거와 automatic reviews

Codex Cloud와 Code review가 설정된 GitHub PR에서는 댓글 한 줄로 review를 시작할 수 있습니다.

@codex review

초점을 좁힐 수도 있습니다.

@codex review for security regressions

Codex review는 PR diff를 읽고, 변경 파일에 가장 가까운 AGENTS.md 지침을 따르며, 기본적으로 높은 우선순위 문제에 집중합니다. 팀은 automatic reviews를 켜서 PR이 opened for review 상태가 될 때 자동으로 실행되게 할 수도 있습니다.

하지만 automatic review는 automatic merge가 아닙니다. P0/P1급 문제를 더 빨리 드러내는 데는 도움이 되지만, business owner, CI, 최종적인 사람의 판단을 대체하지는 않습니다.

Codex review가 잘하는 일	사람이 계속 결정해야 하는 일
명백한 회귀, 빠진 검증, 위험한 권한 변경 찾기	요구사항이 맞는지, trade-off가 받아들일 만한지
AGENTS.md review guidelines에 따라 PR diff 확인	아키텍처 방향, 제품 의미, release 시점
P0/P1 문제에 높은 신호의 comment 남기기	위험을 받아들이고 merge할지

review에서 문제가 나오면 PR context를 기반으로 Codex에게 수정을 요청할 수 있습니다. 예를 들어 @codex fix the P1 issue라고 comment합니다. 이 역시 Cloud task 흐름으로 들어가며, 돌아온 diff는 다시 검토해야 합니다.

@codex가 반응하지 않으면 순서대로 점검하기

PR에 같은 comment를 반복해서 남기지 말고, 먼저 순서대로 확인합니다.

1. 이 repository에 Codex Cloud가 설정되어 있는가.
2. Codex settings에서 이 repository의 Code review가 켜져 있는가.
3. comment가 정확히 @codex review를 포함하는가.
4. automatic review가 켜져 있고 trigger event가 맞는가.
5. GitHub app / repository permission이 PR diff, comment, push branch를 읽고 쓸 수 있는가.
6. workspace/admin policy, GitHub Enterprise, private repo access에 제한이 있는가.
7. usage limit에 도달했는가. 특히 code review limit은 일반 chat usage와 다를 수 있습니다.

Cloud tasks, review comments, review가 아닌 @codex comments의 동작이 다르다면 task, comment, repository, 시간을 기록한 뒤 공식 지원이나 workspace admin에게 확인합니다.

Remote devbox / SSH host는 Cloud가 아닙니다

remote connection을 써야 하는 경우

Local에도 Cloud에도 잘 맞지 않는 작업이 있습니다. 프로젝트가 이미 devbox, GPU 머신, 내부 네트워크, enterprise remote development host에 있는 경우입니다.

구분은 이렇습니다.

• Codex Cloud: OpenAI managed / configured cloud environment입니다. GitHub 리포지토리를 checkout하며, 내 PC를 떠난 리포지토리 작업과 PR workflow에 적합합니다.
• Remote connection / SSH host: Codex app이 remote host에 연결하고, 그 머신의 files, credentials, permissions, plugins, browser setup, local tools를 사용합니다.

작업에 내부 서비스, GPU, 원격 DB, devbox에 이미 설정된 도구가 필요하다면 remote connection이 실제 환경에 더 가깝습니다. 보안 경계도 다릅니다. 해당 host에서 Codex가 사용할 수 있는 permissions, credentials, tools가 곧 여러분이 부여한 경계입니다.

보수적인 설정은 trusted SSH keys와 least-privilege accounts를 쓰고, app-server transport를 public internet에 노출하지 않으며, 네트워크를 넘을 때 VPN이나 mesh networking을 우선하는 것입니다.

보수적인 Codex Cloud SOP

처음 Codex Cloud를 설정한다면 다음 순서가 안전합니다.

1. 리포지토리 상태를 재현할 수 있는 작은 작업을 고르고, 큰 refactoring은 고르지 않습니다.
2. repository에 Cloud environment를 설정합니다.
3. 의존성 설치와 대상 검사를 반복 실행할 수 있게 setup script를 씁니다.
4. setup phase에 필요한 민감한 값만 secrets에 넣고, 민감하지 않은 설정은 env vars에 둡니다.
5. agent internet access는 기본적으로 끕니다. 필요할 때만 필요한 domain과 method를 allowlist합니다.
6. task prompt를 issue처럼 씁니다: Goal, Context, Scope, Environment, Done when, Stop if.
7. 실행 중에는 plan, commands, failures를 봅니다.
8. 완료 후 summary, diff, test results, skipped checks를 읽습니다.
9. 작은 변경은 PR을 만듭니다. 더 위험한 변경은 먼저 check out locally 합니다.
10. PR에서 @codex review를 2차 확인으로 사용합니다.
11. merge 여부는 사람, CI, 팀 프로세스가 결정하게 합니다.
12. 반복되는 review 교훈은 AGENTS.md 규칙으로 바꿉니다.

Cloud를 안정적으로 만드는 것은 더 많은 자동화가 아닙니다. 각 단계에 명확한 경계가 있는 것입니다. environment는 repo를 재현할 수 있어야 합니다. prompt는 실행 가능해야 합니다. diff는 review할 수 있어야 합니다. review 흔적은 추적 가능해야 합니다. 그래야 불확실성을 더 먼 곳으로 던지는 것이 아니라, 명확한 요구사항을 클라우드 Agent에 맡기는 일이 됩니다.