codex-bridge

웹 ChatGPT 가 내 컴퓨터의 프로젝트를 직접 읽고, 고치고, 명령을 돌리고, 필요하면 로컬 Codex CLI 에 작업을 통째로 넘길 수 있게 하는 MCP 서버. Codex 앱에서 하던 작업(사용량 한도로 멈춘 스레드 포함)을 ChatGPT 나 Claude Code 로 끌어와 이어가는 용도로도 쓴다.

AI 에이전트에게 설치 맡기기

Claude Code 나 Codex CLI 에 아래 한 줄을 붙여 넣으면 된다. 에이전트가 필요한 것을 묻고, 스크립트로 할 수 있는 건 전부 하고, 브라우저에서 사람이 해야 할 단계만 안내한다.

https://github.com/Tap-Kim/codex-bridge 의 SETUP.md 를 읽고 그대로 설치해줘

AI 에이전트라면: 설치 요청을 받았을 때 이 README 가 아니라 SETUP.md 의 절차를 따른다. 원문: https://raw.githubusercontent.com/Tap-Kim/codex-bridge/main/SETUP.md

직접 설치하려면 아래를 순서대로 따라 하거나, 클론한 뒤 CODEX_BRIDGE_ROOTS=... scripts/setup.sh 한 번으로 1단계와 로컬 클라이언트 등록을 끝낼 수 있다.

웹 ChatGPT (커넥터, 인증 없음)
  -> OpenAI Secure MCP Tunnel
  -> tunnel-client (내 컴퓨터, Authorization: Bearer 토큰을 붙임, 헬스 포트 7422)
  -> codex-bridge  http://127.0.0.1:7421/mcp
  -> 파일 읽기/쓰기, 허용된 명령 실행, codex exec

구성은 두 개의 상시 프로세스다.

로컬 Codex 앱·CLI 나 Claude Code 에서만 쓸 거라면 터널은 필요 없다. 1단계만 하고 다른 클라이언트에서 쓰기 로 넘어가면 된다.

보안 주의. 연결된 ChatGPT 대화는 허용 루트 안의 파일을 읽고 쓰고, 허용 목록의 명령(git, npm, node 등)을 실행하고, codex exec -s workspace-write 를 돌릴 수 있다. 허용 루트는 꼭 필요한 폴더로 좁히고, 커넥터는 본인 계정에서만 쓴다. .env*, *.pem, *.key, auth.json, .npmrc, .netrc, id_rsa* 는 읽기·쓰기 모두 거부되고 .git/ 안에는 쓰지 못한다.

Related MCP server: ChatGPT MCP Bridge

준비물

• macOS 또는 Linux, Node.js 20 이상, Python 3.9 이상, git

• (선택) Codex CLI 설치 후 로그인 — codex_* 툴을 쓸 때 필요

• (웹 ChatGPT 연결 시) Tunnels 권한이 있는 OpenAI Platform 조직, ChatGPT 개발자 모드

1. 브릿지 실행

설치 없이 바로:

CODEX_BRIDGE_ROOTS="$HOME/work:$HOME/side" npx -y github:Tap-Kim/codex-bridge

또는 클론해서:

git clone https://github.com/Tap-Kim/codex-bridge.git ~/codex-bridge && cd ~/codex-bridge
npm install
CODEX_BRIDGE_ROOTS="$HOME/work:$HOME/side" npm start

CODEX_BRIDGE_ROOTS 는 ChatGPT 가 만질 수 있는 폴더 목록(콜론 구분, 절대 경로)이다. 생략하면 서버를 띄운 현재 폴더 하나만 연다. 첫 실행 때 ~/.codex-bridge/token(64자, 권한 600) 이 생기고, 매 실행마다 tunnel-client 용 ~/.codex-bridge/auth_header(Bearer <token>) 를 다시 쓴다.

상시 실행 (macOS)

클론한 경우 LaunchAgent 로 등록하면 로그인할 때 자동으로 뜨고 죽으면 다시 뜬다.

CODEX_BRIDGE_ROOTS="$HOME/work:$HOME/side" scripts/install-launchd.sh   # 설치·갱신
scripts/install-launchd.sh restart                                       # 브릿지만 안전하게 재시작
scripts/install-launchd.sh uninstall                                     # 제거
tail -f ~/.codex-bridge/logs/local.codex-bridge.err.log

~/.codex-bridge/tunnel.yaml 이 있고 tunnel-client 가 PATH 에 있으면 터널도 같이 등록된다. 터널을 나중에 준비했다면 스크립트를 한 번 더 실행하면 된다. 두 프로세스는 따로 등록되므로 브릿지를 재시작해도 ChatGPT 커넥터 연결은 유지된다.

2. 웹 ChatGPT 연결 (Secure MCP Tunnel)

2-1. tunnel-client 설치

brew install openai/tools/tunnel-client
tunnel-client --version

brew 가 실패하면(예: 베타 macOS 의 Xcode 버전 요구) Homebrew formula 에 적힌 zip 을 받아 formula 의 sha256 과 대조한 뒤 PATH 에 둔다.

V=0.0.14; A=darwin-arm64   # 인텔 Mac: darwin-amd64, 리눅스: linux-amd64 | linux-arm64
curl -fLO "https://persistent.oaistatic.com/tunnel-client/v$V/tunnel-client-v$V-$A.zip"
shasum -a 256 "tunnel-client-v$V-$A.zip"   # formula 의 sha256 과 같아야 한다
unzip "tunnel-client-v$V-$A.zip" -d ~/.local/tunnel-client
export PATH="$HOME/.local/tunnel-client:$PATH"   # 셸 설정 파일에도 추가

zip 안의 cloudflared 가 tunnel-client 와 같은 폴더에 있어야 하므로 심볼릭 링크 대신 폴더를 PATH 에 넣는다.

2-2. 터널과 런타임 키 만들기

1. https://platform.openai.com/settings/organization/tunnels -> Create tunnel -> tunnel_... ID 복사

2. 같은 터널 설정의 ChatGPT workspaces 에 내 ChatGPT 계정 ID 를 추가한다. 이름 검색은 안 되고 정확한 ID 를 넣어야 한다. 개인 계정의 ID 는 로그인한 브라우저에서 https://chatgpt.com/api/auth/session 을 열었을 때 account.id 값(UUID). 이게 빠지면 커넥터 폼의 터널 목록에 아무것도 안 뜬다.

3. https://platform.openai.com/settings/organization/api-keys -> 이 용도 전용 런타임 키 발급(admin 키 아님). 키를 발급하는 계정에 Tunnels Read + Use 권한이 있어야 한다.

printf '%s' 'sk-...런타임키...' > ~/.codex-bridge/api_key && chmod 600 ~/.codex-bridge/api_key

2-3. 프로파일 작성 후 실행

tunnel.example.yaml 을 ~/.codex-bridge/tunnel.yaml 로 복사하고 REPLACE_ME 두 군데(터널 ID, 홈 경로)를 채운다.

cp tunnel.example.yaml ~/.codex-bridge/tunnel.yaml && chmod 600 ~/.codex-bridge/tunnel.yaml
# 편집 후
tunnel-client doctor --profile-file ~/.codex-bridge/tunnel.yaml --explain
tunnel-client run    --profile-file ~/.codex-bridge/tunnel.yaml
curl -s 127.0.0.1:7422/readyz   # 200 이면 준비 완료

상시 실행은 1단계의 scripts/install-launchd.sh 를 다시 실행하면 된다. 터널 ID 하나에는 tunnel-client 하나만 붙인다.

2-4. ChatGPT 에 커넥터 추가

tunnel-client 가 떠 있는 동안에만 만들 수 있고, 떠 있는 동안에만 동작한다.

1. chatgpt.com 설정 -> 보안 -> 개발자 모드 켜기

2. https://chatgpt.com/plugins 상단의 앱 만들기 (설정 화면이 아니라 이 페이지에 있다)

3. 이름 codex-bridge -> 연결 방식 터널 -> 2-2 에서 만든 터널 선택 -> 인증 인증 없음 -> 위험 고지 체크 -> 만들기 -> 연결하기

4. 새 대화에서 커넥터를 켜고 "list_projects 로 프로젝트 목록 보여줘" 로 확인

인증 없음이어도 괜찮은 이유: ChatGPT 와 터널 사이는 OpenAI 가 워크스페이스로 인증하고, 터널과 브릿지 사이는 tunnel-client 가 Bearer 토큰을 붙인다. 브릿지는 토큰 없는 요청을 401 로 막는다.

다른 클라이언트에서 쓰기

터널 없이 127.0.0.1:7421 로 바로 붙는다. 토큰을 재발급했다면(~/.codex-bridge/token 삭제 후 재시작) 아래 설정의 토큰도 다시 넣어야 한다.

Codex 앱·CLI

cat >> ~/.codex/config.toml <<EOF

[mcp_servers.codex-bridge]
url = "http://127.0.0.1:7421/mcp"
http_headers = { Authorization = "Bearer $(cat ~/.codex-bridge/token)" }
EOF

슬래시 명령 두 개를 같이 설치하면 편하다.

mkdir -p ~/.codex/prompts && cp codex/prompts/*.md ~/.codex/prompts/

Claude Code

claude mcp add --transport http codex-bridge http://127.0.0.1:7421/mcp \
  --header "Authorization: Bearer $(cat ~/.codex-bridge/token)"

"codex_handoff 로 Codex 에서 하던 작업 가져와서 이어서 해줘" 처럼 쓰면 된다.

툴

웹 ChatGPT 에는 MCP 프롬프트 메뉴가 없어서, 서버 안내문(instructions)에 Codex 식 명령을 넣어 두었다. 메시지를 /goal <목표>, /review, /diff, /status, /plan <작업>, /resume [thread_id] 로 시작하면 그대로 따른다.

Loop Engineering

긴 작업은 codex_loop_start 에 목표와 명시적인 검증 명령을 함께 넘긴다. MCP 서버는 실행만 요청하고 실제 loop는 별도 Python worker가 맡는다. worker는 Codex 실행 → 검증 → 실패 원인 요약 → 같은 thread_id resume 을 max_attempts 범위에서 반복한다. 검증 명령은 run_command 와 같은 allowlist를 사용하고 셸을 거치지 않는다.

상태는 CODEX_BRIDGE_STATE/loops/<loop_id>.json 에 원자적으로 저장되고 worker는 loop별 flock을 잡는다. 그래서 ChatGPT 연결이나 Node 브릿지가 재시작돼도 이미 실행 중인 worker는 계속 동작한다. worker 자체가 죽은 경우에는 다음 브릿지 시작 시 stale active loop를 찾아 checkpoint와 저장된 thread_id 로 자동 복구한다. thread가 만들어지기 전에 끊긴 경우에도 같은 loop_id 를 유지한 채 새 Codex 실행으로 이어간다.

worker는 기본 5초마다 heartbeat를 기록하고, Codex stdout/stderr activity가 기본 300초 동안 없으면 hang으로 판정한다. hang이면 먼저 SIGTERM, 종료되지 않으면 SIGKILL로 정리한 뒤 같은 thread를 다시 resume한다. watchdog_interval_sec, hang_timeout_sec, terminate_grace_sec 은 loop 시작 시 조정할 수 있다. 취소는 별도 cancel marker로 먼저 영속화해 watchdog과 race가 나도 다시 실행되지 않는다.

검증 명령을 생략한 loop는 Codex의 자체 완료 메시지만으로 성공 처리하지 않고 verification_required 에서 멈춘다. 이후 codex_loop_resume 에 verify_commands 를 전달해 외부 검증을 추가할 수 있다. 검증 실패나 hang/process failure가 max_attempts 에 도달하면 무한 반복하지 않고 blocked 로 종료한다.

같은 오류 fingerprint가 반복되면 단순 retry 대신 전략을 단계적으로 바꾼다. 2회째에는 이전 수정 방식 재사용을 금지하고 다른 구현 접근을 요구하고, 3회째에는 가정과 실제 런타임 증거를 다시 확인하는 root-cause reset, 4회째부터는 구현 경계·의존성·제어 흐름까지 재검토하는 architecture escalation 지시를 다음 Codex resume prompt에 넣는다. 현재 단계와 반복 횟수는 loop state의 strategy_level, strategy_repeat_count, failure_fingerprints 에 남는다.

MCP 응답 대기와 실제 작업 시간

codex_run/resume/status, Loop/Graph의 시작·재개·상태 조회는 요청한 wait_sec가 길어도 한 호출에서 최대 20초만 기다린다. 완료되지 않았으면 job/loop/graph ID와 현재 상태를 먼저 반환하고, 작업은 계속 진행한다. 해당 status 도구로 짧게 폴링한다. CODEX_BRIDGE_MAX_WAIT_SEC로 이 응답 대기를 더 짧게 조정할 수 있다 (0.1~20초).

run_command도 서버를 차단하지 않고 실행한다. 빠른 명령은 기존 출력 문자열을 반환하고, 긴 명령은 kind=command, job_id, status=running을 반환한다. codex_status(job_id)로 완료 출력(final_message)을 확인하거나 codex_cancel(job_id)로 취소한다. timeout_sec는 실제 명령 실행 제한이며 짧은 MCP 응답 대기와 별개다.

ChatGPT에서 호출 시간이 초과돼도 작업이 반드시 실패한 것은 아니다. 이미 받은 ID로 상태를 먼저 확인하고, 동일 목표를 새 작업으로 중복 실행하지 않는다. 장기 작업은 상태가 저장되는 Loop/Graph를 사용한다. 일반 job/command ID와 완료 결과는 재시작 후에도 조회할 수 있지만 중단된 실행은 자동 재실행하지 않는다.

PC 자동 복구 감시

기존 브릿지·터널을 설치한 macOS에서 python3 scripts/install-recovery.py를 실행하면 PC에서 30초마다 점검하는 독립 LaunchAgent를 등록한다. daimon 사용 시 bridge-recovery scheduled job으로 나타난다. ChatGPT 연결이 없어도 실행된다. macOS의 Documents TCC 제한을 피하기 위해 watchdog과 supervisor 런타임 복사본은 ~/.codex-bridge/recovery-runtime에서 실행하며, 설치 스크립트를 다시 실행하면 현재 저장소 버전으로 갱신된다.

• 3회 연속 readiness 실패 시 해당 서비스만 복구한다. 브릿지가 정상화되기 전에 터널을 재시작하지 않는다.

• 재시작은 최소 5분 간격, backoff 최대 30분, 전체 시간당 최대 3회로 제한한다. 반복 실패는 attention_required로 남긴다.

• 브릿지의 진행 작업·새 작업 유입을 확인한다. 재시작 준비 시 새 요청을 잠깐 차단하며, 살아 있는 작업 또는 확인할 수 없는 상태에서는 강제 재시작하지 않는다.

• 완료 결과와 job ID는 private CODEX_BRIDGE_STATE/jobs에 저장한다. 응답을 놓쳤으면 codex_jobs로 ID를 찾고 codex_status로 조회한다. 중단된 일반 job은 interrupted로 보고하고 자동 재실행하지 않는다. 저장된 Loop/Graph는 기존 ID와 flock·attempt 제한·cancel marker에 따라 복구한다.

• codex_recovery_status로 상태를 조회한다. 건강한 서비스를 단일 502나 ChatGPT 화면 오류만으로 재시작하지 않는다. ChatGPT 자체 스트림 복구는 로컬 감시가 보장하지 않는다.

설정과 상태는 recovery-config.json, recovery-state.json에 저장된다. 종료하려면 daimon에서 bridge-recovery를 Disable한다. 기존 토큰, 터널 프로파일, 허용 루트는 변경하지 않는다.

Task Graph / Multi-worker

서로 독립적으로 진행 가능한 작업은 codex_graph_start 로 DAG를 전달할 수 있다. Graph supervisor는 원본 working tree가 clean인지 확인한 뒤 task마다 별도 git worktree와 codex_loop_* worker를 만들고, dependency가 모두 통합된 task만 시작한다. max_parallel 범위에서 독립 task는 실제로 동시에 실행된다.

각 task가 자체 verifier를 통과하면 임시 branch에 commit하고, private integration worktree에서 topological order로 cherry-pick한다. 병렬 task가 같은 코드를 충돌되게 수정하면 원본에는 아무것도 적용하지 않고 graph를 blocked / merge_conflict 로 멈춘다. integration worktree에는 충돌 파일과 index를 남겨 수동으로 해결할 수 있다. dependency task는 선행 task가 integration된 commit을 기준으로 새 worktree를 만들기 때문에 선행 결과를 볼 수 있다.

모든 task가 통합되면 final_verify_commands 를 integration worktree에서 실행한다. 최종 verifier가 없으면 verification_required 로 멈추며 codex_graph_resume 에 verifier를 추가해 재개할 수 있다. 최종 검증이 통과한 뒤에도 원본 working tree의 HEAD나 파일이 graph 시작 이후 바뀌었다면 자동 덮어쓰지 않고 integration_ready 로 멈추고 patch를 보존한다.

원본이 그대로 clean이면 integration branch 전체 diff를 원본 working tree에 커밋 없이 적용한다. 따라서 graph 내부 병렬 작업용 임시 commit은 사용자 브랜치 history에 들어가지 않는다. Graph 상태는 CODEX_BRIDGE_STATE/graphs, 격리 worktree는 CODEX_BRIDGE_STATE/graph-worktrees 아래에 저장되며 graph worker도 flock과 startup recovery를 사용한다.

시작 예시 (MCP tool arguments):

{
  "cwd": "/absolute/path/to/clean-repo",
  "max_parallel": 2,
  "tasks": [
    {"task_id": "api", "goal": "Implement the API change", "write_paths": ["src/api"], "verify_commands": [{"command": "npm", "args": ["test", "--", "api"]}]},
    {"task_id": "ui", "goal": "Implement the UI change", "write_paths": ["src/ui"], "verify_commands": [{"command": "npm", "args": ["test", "--", "ui"]}]},
    {"task_id": "integration", "goal": "Add integration coverage", "depends_on": ["api", "ui"], "write_paths": ["test"], "verify_commands": [{"command": "npm", "args": ["test"]}]}
  ],
  "final_verify_commands": [{"command": "npm", "args": ["test"]}],
  "apply_to_base": true
}

제약과 종료 상태:

• cwd는 clean git working tree의 루트여야 한다. staged/unstaged/untracked 변경이 있으면 시작을 거부한다. submodule 저장소와 reftable reference storage는 지원하지 않는다.

• task의 write_paths는 수정 가능한 상대 파일/디렉터리 목록이다. 범위 밖 변경은 통합 전에 제거하고 task verifier를 다시 실행한다. []는 변경 없는 task에 사용한다. worktree는 파일 격리이며 보안 sandbox를 대체하지 않는다.

• 각 task와 graph에 명시적 verifier를 제공한다. final verifier는 검증 대상 tracked/untracked 파일이나 HEAD를 변경하면 안 된다 (ignored 빌드 산출물은 가능).

• apply_to_base=false이면 검증된 patch와 integration worktree를 보존하고 integration_ready에서 멈춘다. resume도 이 설정을 유지한다. base 변경 시에는 integration_ready / base_changed로 멈추며 강제 적용 옵션은 없다.

• apply 도중 worker가 중단되면 자동 재적용하지 않고 integration_ready로 남긴다. patch와 base diff를 비교한 뒤 직접 처리한다. 최종 재검증과 적용 중에는 base의 Git index.lock, HEAD.lock, 현재 branch ref lock을 잡아 다른 graph와 Git 변경을 차단한다. 잠금 파일은 기존 파일을 덮어쓰지 않으며, base_locked면 해당 작업이 끝난 뒤 resume한다. 재시작 시 graph가 직접 만든 잠금만 회수한다. 일반 editor는 Git 잠금을 따르지 않으므로 최종 적용 중 base를 편집하지 않는다.

• 완료·취소 시 private worktree/branch를 정리한다. 충돌·검증 실패·integration-ready 상태는 조사용으로 보존하며 codex_graph_cancel로 정리할 수 있다. merge conflict는 명시적인 수동 해결 재개가 필요하다.

충돌 수동 해결:

1. codex_graph_status의 conflict_resolution.worktree에서 충돌 파일을 수정한다. base working tree는 편집하지 않는다.

2. 해당 integration worktree에서 git add -- <해결한 파일>로 변경을 stage한다. 직접 commit하지 않는다.

3. codex_graph_resume에 {"graph_id":"...", "resolve_conflict":true}를 전달한다. 미해결 index, unstaged/untracked 변경, task의 write_paths 밖 변경은 resolution_error와 함께 거부된다.

4. supervisor가 충돌 task의 verifier를 실행하고 private 해결 commit을 만든다. 충돌로 중지된 다른 task는 새 child loop로 다시 시작하고, dependent task는 해결된 integration 결과를 기준으로 실행한다. 마지막으로 final_verify_commands를 다시 통과해야 base에 적용한다.

수동 해결 checkpoint가 저장된 뒤 worker가 중단돼도 검증된 동일 결과로 이어간다. 재개 중에는 integration worktree도 편집하지 않는다. integration_base checkpoint가 있는 이전 graph는 충돌이 abort됐더라도 같은 integration HEAD에서 해결 내용을 stage해 재개할 수 있다. checkpoint가 없는 legacy graph는 새 graph로 시작한다.

Codex 작업을 이어받는 흐름:

1. "codex_handoff 로 Codex 에서 하던 작업 가져와" -> 스레드 요약과 git 상태

2. 더 필요하면 codex_session_read 로 대화록, git_diff 로 실제 변경

3. Codex 에 계속 맡기려면 codex_resume, 직접 하려면 read_file / edit_file / run_command

환경 변수

툴 호출 기록(툴 이름과 경로만)은 ~/.codex-bridge/access.log 에 쌓인다.

문제 해결

개발

npm install
npm test          # 임시 폴더와 가짜 ~/.codex 로 서버를 띄워 툴 전체를 점검한다

• server.mjs 는 무상태 Streamable HTTP MCP adapter이고, 요청마다 새 McpServer 를 만든다

• loop_supervisor.py 는 장기 loop의 프로세스 소유권, heartbeat/watchdog, checkpoint/recovery, 반복 오류 전략 전환을 담당한다

• graph_supervisor.py 는 dependency scheduling, 격리 worktree 병렬 실행, deterministic integration, 최종 검증과 base patch 적용을 담당한다

• test.mjs 는 fake Codex로 loop 복구뿐 아니라 병렬 graph, dependency 순서, 최종 verifier attach/resume, merge conflict, 취소, base 변경, stale recovery와 중단 checkpoint 복구까지 검증하며 실제 ~/.codex 나 홈 디렉터리를 건드리지 않는다

• scripts/setup.sh 는 에이전트용 원샷 설치(재실행 안전), scripts/install-launchd.sh 는 LaunchAgent 등록만 한다. 설치 흐름을 바꾸면 SETUP.md 도 같이 고친다

• PR 마다 GitHub Actions 가 macOS·Ubuntu 에서 npm test 를 돌린다

참고

dreamurl/GPT-Bridge, xq3427/WebCodex 를 참고해 최소한으로 다시 만들었다. tunnel-client 는 openai/tunnel-client (Apache-2.0).

라이선스

MIT