FOLLOW-UP · PRACTICAL RUNBOOK

설정은 끝났다. 이제 한 줄로 전환한다: Claude Code 세션을 GPT-6 Astra로 이어 쓰는 Windows 운영 플레이북

앞 글에서 브리지를 붙였다면, 이제 필요한 것은 매번 다시 조사하는 일이 아니라 실행 → 검증 → 세션 연속성 확인 → 문제 발생 시 최소 조치가 반복 가능한 운영 절차다.

분야 · AI 개발 도구 / 운영환경 · Windows · PowerShell형식 · 따라 하는 Runbook

이 글은 앞선 설정 가이드의 후속편이다. 목표는 새 도구를 하나 더 배우는 것이 아니라, 이미 구축한 Claude Code ↔ Codex 브리지를 매일 같은 방식으로 안전하게 재실행하는 것이다.

먼저 범위를 분명히여기서 사용하는 codex-for-claude-code는 OpenAI나 Anthropic이 공식적으로 제공하는 기능이 아니라, 외부 개발자가 만든 오픈소스 브리지다. 단순히 Claude Code 안에서 Codex에 리뷰나 작업을 위임하려는 목적이라면 OpenAI의 공식 codex-plugin-cc가 더 직접적인 선택이다. 이 글의 목적은 Claude Code TUI와 세션 흐름을 유지하면서 Codex/Astra를 백엔드처럼 쓰는 특수한 운영 방식을 기록하는 것이다.

또 하나 달라진 점이 있다. 2026년 9월 초의 실증 기록과 현재 공개 버전의 동작이 완전히 같지는 않다. 따라서 아래 절차는 직접 관측했던 동작과 현재 upstream 문서를 분리해 설명한다.

Astra 모델	공식 모델 ID는 `gpt-6-astra`. OpenAI는 1,050,000 토큰 컨텍스트를 공표한다.
Codex CLI	Astra API 구성 지원이 0.153.1 릴리스에 들어왔고, 0.153.4에서는 번들 모델 피커 표시와 기본 모델 동작이 수정됐다.
브리지	현재 upstream README는 Node.js 20+, 로그인된 Codex CLI를 요구하며 로컬 127.0.0.1:3099 프록시를 사용한다고 설명한다.
세션	예전 0.2.6 실증에서는 수동 JSONL 복사가 필요했지만, 현재 upstream은 세션/히스토리 상호운용성을 지원한다고 안내한다. 따라서 수동 복사는 폴백으로만 둔다.

공식/원문 확인: GPT-6 Astra 모델 문서 · Codex 릴리스 · codex-for-claude-code README

Claude Code에서 로컬 codex-for-claude-code 브리지를 거쳐 Codex CLI의 GPT-6 Astra로 연결되는 전체 구조

평소에는 이것만: 30초 재실행

한 번 구축을 끝낸 PC라면 긴 명령을 다시 입력할 이유가 없다. 아래 다운로드 패키지에 포함한 공개용 스크립트 nv-codex.ps1를 프로젝트 루트에서 실행한다.

.\nv-codex.ps1

프로젝트가 현재 디렉터리가 아니라면 경로를 명시한다.

.\nv-codex.ps1 -ProjectPath "C:\path\to\your-project"

세션 선택 화면이 뜨면 기존 세션을 고르거나, UUID를 알고 있다면 바로 resume한다.

.\nv-codex.ps1 -ProjectPath "C:\path\to\your-project" -Resume "<SESSION_UUID>"

성공 기준세션이 열리는 것만으로는 성공이 아니다. 바로 /status를 실행하고 base URL, model, 과거 대화 세 항목을 확인한 뒤에 작업을 시작한다.

이 PC에서 처음이라면: 최초 구축 4단계

B1. 사전 점검

.\nv-codex.ps1 -Check

수동으로 보면 핵심은 다음이다.

node --version
claude --version
codex --version
claude-codex --version

현재 브리지 upstream은 Node.js 20 이상을 요구한다. Astra를 직접 모델로 구성하는 경로는 Codex 0.153.1에서 명시적으로 추가됐고, 0.153.4에서는 Astra의 번들 모델 피커 표시가 수정됐다. 따라서 새 구축은 최신 안정판으로 올린 뒤 시작하는 편이 안전하다.

npm install -g @openai/codex@latest

B2. Codex 로그인

codex login

브리지의 목적이 ChatGPT 계정에 포함된 Codex allowance를 사용하는 것이라면 로그인 화면에서 ChatGPT 계정 경로를 사용한다. 임의의 제3자 base URL이나 API router를 섞으면 이 글의 검증 전제가 깨진다.

B3. 브리지 설치

npm install -g codex-for-claude-code@latest

설치 뒤 claude-codex --help로 --model과 --resume이 현재 버전에서도 존재하는지 먼저 확인한다.

B4. 직접 실행

claude-codex --model gpt-6-astra

공개용 스크립트의 기본 모델은 gpt-6-astra로 두었다. [1m] 같은 접미사는 공식 모델 ID가 아니라 클라이언트/브리지 측 힌트일 수 있으므로 기본값으로 강제하지 않는다.

재실행, 최초 구축, 30초 검증, 증상별 문제 해결, Claude 복귀로 이어지는 GPT-6 Astra 5단계 운영 절차 — 평소에는 한 줄 재실행, 처음 한 번은 구축, 이후에는 30초 검증과 증상별 조치, 필요할 때 안전하게 Claude로 복귀한다.

검증은 30초지만 건너뛰면 안 된다

이 구성에서 가장 위험한 실패는 오류가 크게 나는 실패가 아니다. 정상적으로 보이는데 실제로는 원하는 경로가 아닌 상태다.

확인 항목	정상 값	어긋났을 때
`Anthropic base URL`	`http://127.0.0.1:3099`	`api.anthropic.com`이면 브리지 전환 실패
`Model`	`gpt-6-astra` 계열	다른 기본 모델이면 silent fallback 의심
세션 내용	이전 대화와 문맥이 실제로 보임	빈 세션이면 resume/세션 가시성 문제

브리지 upstream도 로컬 프록시를 기본적으로 127.0.0.1:3099에서 띄운다고 설명한다. 401이 나오면 Codex CLI를 한 번 실행해 OAuth 토큰을 갱신한 뒤 다시 브리지를 실행하라는 트러블슈팅도 제공한다.

# OAuth 갱신이 의심될 때
codex

# 그 다음 브리지 재실행
claude-codex --model gpt-6-astra

모델 피커 설명은 버전 민감초기 Astra 지원 시점의 Codex 0.153.1은 API로 구성하면서 피커에는 숨기는 동작이 있었다. 그러나 0.153.4는 Astra의 번들 모델 피커 표시를 수정했다. 따라서 “피커에 Astra가 없으면 무조건 정상”이라고 외우지 말고, 현재 버전과 /status를 함께 본다.

세션은 먼저 직접 이어 보고, 복사는 마지막 폴백으로

이 부분이 이전 실증 기록과 현재 upstream 사이에서 가장 크게 달라진 지점이다. 예전 Windows + 브리지 0.2.6 환경에서는 일반 Claude Code의 JSONL이 ~/.claude에 있고 브리지는 ~/.claude-codex를 보면서 --resume이 바로 실패했다. 그래서 특정 JSONL 하나를 수동으로 복사했다.

하지만 현재 브리지 README는 최신 빌드가 공유 Claude 자산을 연결해 session/history interoperability를 유지한다고 설명하고, plain Claude 세션이 보이지 않을 때는 두 TUI를 재시작해 공유 설정 트리를 다시 읽도록 권한다. 따라서 현재 공개 절차는 다음 순서가 더 안전하다.

순서	조치
1	그냥 `claude-codex --model gpt-6-astra --resume <UUID>` 시도
2	세션이 안 보이면 Claude와 bridge TUI를 모두 종료하고 재실행
3	그래도 `No conversation found`면 브리지 버전과 설정 디렉터리 확인
4	마지막으로만 다운로드 스크립트의 `-Import`를 사용해 특정 JSONL 하나 복사

.\nv-codex.ps1 `
  -ProjectPath "C:\path\to\project" `
  -Import "<SESSION_UUID>"

Import를 반복하지 말 것브리지 쪽 사본에서 이미 작업을 진행했다면 원본 JSONL을 다시 덮어쓰는 순간 그 이후 기록이 사라질 수 있다. 동봉 스크립트는 기존 대상이 있으면 기본적으로 중단하고, -Force를 명시했을 때만 타임스탬프 백업 후 덮어쓴다.

일반 Claude Code의 세션 JSONL을 브리지 환경으로 필요한 파일만 이관하고 기존 파일을 백업하는 안전한 세션 관리 구조 — 세션 기록은 실시간 동기화가 아니다. 한 시점에는 한쪽만 사용하고, 필요할 때 특정 세션만 백업 후 안전하게 이관한다.

Windows에서 한글 CLAUDE.md가 깨지면 먼저 인코딩을 확인

대형 프로젝트에서 CLAUDE.md가 프로젝트 전체의 작업 규칙을 정의하는 문서라면 한글 깨짐은 단순한 화면 표시 문제가 아니다. 모델이 규칙 자체를 잘못 읽을 수 있다. 특히 Windows PowerShell 5.1의 Get-Content는 BOM 없는 UTF-8 파일을 시스템 ANSI로 해석할 수 있다.

powershell.exe -Command "Get-Content -LiteralPath CLAUDE.md -TotalCount 3"
powershell.exe -Command "Get-Content -LiteralPath CLAUDE.md -TotalCount 3 -Encoding UTF8"

두 번째 명령에서만 한글이 정상이라면 인코딩 경로가 원인일 가능성이 높다.

대응은 영향 범위를 보고 선택UTF-8 BOM 추가는 PowerShell 5.1 인식에는 도움이 되지만 파일 바이트가 바뀐다. sealed hash나 생성물 검증이 있는 저장소라면 먼저 영향을 확인한다. 가능하면 PowerShell 7(pwsh) 사용이나, 에이전트 지침에 -Encoding UTF8을 명시하는 방법부터 검토한다.

막혔을 때는 증상 하나만 찾아간다

증상	최소 조치
401 Unauthorized	먼저 `codex`를 한 번 실행해 OAuth 갱신 후 재시도
Could not find Claude Code binary	`CLAUDE_CODEX_CLAUDE_BIN`에 실제 Windows 경로 지정
Git Bash에서 Claude 경로 실패	`cygpath -w`로 Windows 경로로 변환
Astra가 실제로 안 잡힘	`codex exec --model gpt-6-astra ...`로 Codex 자체와 브리지를 분리 판정
피커에 Astra 없음	Codex 버전 확인. 0.153.1의 숨김 동작과 0.153.4 이후 동작을 구분
resume에 세션 없음	현재 upstream 상호운용성 경로 재시작 → 그래도 실패하면 수동 Import 폴백
포트 3099 충돌	브리지 프로세스/health 확인 또는 upstream이 지원하는 대체 포트 사용
한글만 깨짐	PowerShell 5.1 + UTF-8 BOM/Encoding 경로 확인

Codex 자체인지 브리지 문제인지 분리

codex exec --model gpt-6-astra "Read README.md and summarize it. Do not change files."

여기서 Astra가 정상 실행되는데 claude-codex에서만 문제가 나면 브리지 계층으로 범위를 줄일 수 있다. 반대로 여기서부터 실패하면 Codex 버전·로그인·계정 가용성을 먼저 본다.

Claude로 돌아갈 때: 한 시점에 한쪽만 사용

세션을 파일 단위로 복사하거나 브리지 쪽에서 별도의 히스토리를 기록하는 순간, 그것은 데이터베이스 복제처럼 자동 병합되는 동기화가 아니다. 같은 출발점에서 두 개의 기록이 생길 수 있다.

Claude와 Astra 브리지 쪽을 같은 세션으로 동시에 진행하지 않는다.
브리지에서 중요한 설계 결정을 내렸다면 HANDOFF.md 같은 짧은 문서로 결정·근거·미완료 작업을 기록한다.
브리지 사본을 다시 ~/.claude로 되돌릴 때는 원본을 먼저 타임스탬프 백업한다.
복귀 절차가 아직 내 환경에서 충분히 검증되지 않았다면, 전체 JSONL을 덮어쓰기보다 handoff 문서를 새 Claude 세션에 주입하는 편이 보수적이다.

복귀는 ‘그냥 원래 claude 실행’과 다르다원래 Claude를 실행하는 것 자체는 쉽지만, 브리지에서 진행한 대화 기록까지 원본 세션에 합치는 문제는 별개다. 자동 병합을 전제로 하지 않는다.

공개용 PowerShell 스크립트가 하는 일

다운로드 패키지의 nv-codex.ps1는 개인 PC 경로를 제거한 공개용 버전이다. 기본적으로 현재 디렉터리를 프로젝트로 사용하며 필요할 때 -ProjectPath로 지정한다.

DOWNLOAD · WINDOWS POWERSHELL

nv-codex.ps1 실행 패키지

이 글에서 사용하는 공개용 PowerShell 스크립트를 ZIP으로 묶었다. nv-codex.ps1, 사용법, SHA-256 체크섬이 포함되어 있다.

Windows PowerShell nv-codex.ps1 4.6 KB

ZIP 파일 다운로드

파일명 · claude-code-gpt-6-astra-windows-playbook.zip
SHA-256 · 0696abb25234871d0135a9efced1db316d8e1ae4c196dfeb599700a249c97195

실행 전 README.txt와 스크립트 내용을 먼저 확인하고, 처음에는 .\nv-codex.ps1 -Check로 환경 점검부터 수행한다.

옵션	역할
`-Check`	도구와 버전, 프로젝트 경로, Claude 바이너리, CLAUDE.md BOM 상태만 점검
`-Resume <UUID>`	특정 세션을 직접 resume
`-Import <UUID>`	직접 resume이 실패한 환경에서만 JSONL 하나를 안전하게 복사한 뒤 resume
`-Force`	기존 bridge 사본이 있을 때 백업을 만든 뒤 Import 허용
`-Model`	기본 `gpt-6-astra`. 비표준 접미사는 사용자가 명시할 때만

# 가장 보수적인 첫 점검
.\nv-codex.ps1 -Check

# 평상시
.\nv-codex.ps1

# 세션 UUID를 바로 지정
.\nv-codex.ps1 -Resume "<SESSION_UUID>"

# direct resume이 정말 실패한 경우에만
.\nv-codex.ps1 -Import "<SESSION_UUID>"

이 방법을 쓰지 않는 편이 나은 경우

새 프로젝트라 세션 연속성이 필요 없다면 Codex CLI를 직접 쓰는 편이 단순하다.
Claude Code 안에서 Codex의 리뷰·위임 기능만 필요하다면 OpenAI 공식 codex-plugin-cc를 먼저 검토한다.
회사/고객 환경에서 비공식 프록시 사용이 허용되지 않는다면 이 브리지를 배포하지 않는다.
보안·규정상 OAuth 토큰을 로컬 제3자 코드가 읽는 구조 자체가 허용되지 않는 환경에서는 사용하지 않는다.

즉 이 플레이북은 개인 개발 환경에서 Claude Code의 작업 감각과 기존 세션을 최대한 유지하면서, ChatGPT/Codex 쪽 모델을 이어 쓰려는 경우에만 의미가 있다.

최종 체크리스트

	게시 후에도 기억할 것
□	Codex와 bridge를 최신 안정판으로 확인했다
□	기본 모델 ID를 `gpt-6-astra`로 명시했다
□	`/status`에서 localhost:3099, Astra, 기존 세션을 확인했다
□	세션이 안 보인다고 바로 JSONL을 덮어쓰지 않았다
□	수동 Import 전에 대상 사본 존재 여부와 백업을 확인했다
□	한글 문서가 깨지지 않는지 확인했다
□	Claude와 bridge를 같은 세션으로 병렬 사용하지 않는다

한 줄 요약평소에는 스크립트 한 줄이면 된다. 다만 전환 성공 여부는 반드시 /status의 세 항목으로 확인하고, 세션 복사는 direct resume과 재시작이 실패했을 때만 쓰는 폴백으로 남겨둔다.

참고 자료: OpenAI GPT-6 Astra · GPT-6 Astra API model · OpenAI Codex releases · codex-for-claude-code · OpenAI codex-plugin-cc