AI 튜토리얼

ccodex-sleep-state 튜토리얼: Codex를 시각적으로 관리하고 프록시를 구성하며 연결 문제 해결하기

이 튜토리얼에서는 Windows와 macOS에 ccodex-sleep-state를 설치하고 Codex에 연결하는 방법, 프록시와 turn-state 전략을 구성하는 방법, 로컬 패널과 진단 명령을 사용해 속도 제한, 구성 충돌 및 연결 장애를 해결하는 방법을 소개합니다.

2026년 9월 18일약 18분 소요

ccodex-sleep-state 튜토리얼: Codex 관리, 프록시 구성 및 연결 문제 해결

프로젝트 소개

ccodex-sleep-state는 Go로 작성된 로컬 도구로, Codex 사용 중 발생할 수 있는 응답 품질 변화, 속도 제한, 연결 실패 및 구성 충돌 문제를 개선하는 것을 목표로 합니다. 연결 관리, 프록시 출구, turn-state 수집, 구성 인계 및 장애 진단을 하나의 로컬 서비스와 웹 패널에 통합하여 구성 파일을 수동으로 수정해야 하는 작업을 줄입니다.

먼저 분명히 해야 할 점은 이 도구가계정 한도를 늘려 주지 않으며, 출구를 변경한 후 모델 품질이 반드시 회복된다고 보장하지도 않는다는 것입니다. 이 도구는 연결, 구성 및 응답의 X-Codex-Turn-State를 처리하여 수집 결과, 주입 상태, 요청 경로와 오류 원인을 더 쉽게 확인할 수 있도록 합니다.

현재 프로젝트는 아직 공개 테스트 버전입니다. Release마다 기능이 다를 수 있으므로 다운로드한 버전의 릴리스 노트를 기준으로 해야 합니다. 일부 모델이나 압축 과정의 테스트 성공을 모든 시나리오가 검수 완료되었다는 의미로 이해해서는 안 됩니다.

핵심 기능

로컬 웹 패널: Codex가 인계되었는지, 요청이 서비스를 통과하는지, 세션 상태와 요청 횟수를 확인합니다.
turn-state 수집 및 주입: 후보 출구에서 짧은 요청을 보내 응답의 state를 확인하고, 이후 요청에서 규칙에 따라 사용합니다.
다양한 인증 방식: 공식 ChatGPT 로그인, OpenAI 공식 API key, Responses 중계 또는 CCS API key를 각각 처리합니다.
모델 격리: gpt-6-astra, gpt-5.6-sol, gpt-5.6-terra를 지원합니다. state는 계정, 자격 증명 및 모델별로 격리되며 모델 간에 혼용되지 않습니다.
프록시 및 구독: HTTP, HTTPS, SOCKS5와 Clash/Mihomo YAML, 줄 단위 URI 및 Base64 URI 구독을 지원합니다.
구성 보호: 인계 전에 Codex 구성을 백업하고 서비스 중지 시 복원을 시도합니다. 구성이 손상되면 복구 패널로 진입할 수 있습니다.
진단 기능: 비식별화된 진단 정보를 다운로드하거나 doctor 명령으로 문제 해결 정보를 수집할 수 있습니다.

설치 전 준비

먼저 이 도구를거치지 않은 상태에서 Codex가 정상적으로 작동하는지 확인합니다. 공식 계정은 먼저 로그인을 완료해야 하며, 중계 서비스를 사용하는 경우 자체 API key를 먼저 구성해야 합니다.

CCS 또는 CC Switch를 함께 사용하는 경우, 이번에 사용할 provider, 상위 서버 및 인증 구성을 먼저 선택한 다음 Codex를 종료하고 구성 전환을 일시 중지합니다. ccodex-sleep-state는 CCS의 계정 데이터베이스를 인계하지 않습니다. Codex에서 현재 선택한 provider만 읽고, 진입점을 일시적으로 로컬 서비스에 연결합니다.

올바른 설치 패키지 선택

프로젝트의 Releases 페이지를 엽니다.
일반 Windows 컴퓨터는 windows-amd64를 선택합니다.
Windows ARM 장치는 windows-arm64를 선택합니다.
Apple 칩 Mac은 darwin-arm64를 선택합니다.
Intel Mac은 darwin-amd64를 선택합니다.
다운로드 후 전체 압축을 해제합니다. 압축 파일에서 단일 파일만 직접 실행하지 마세요.

시작 및 초기화

시작 스크립트 사용

Windows 사용자는 start.cmd를, macOS 사용자는 start.command를 두 번 클릭합니다. 서비스가 시작되면 브라우저가 일반적으로 로컬 관리 패널을 자동으로 열고 현재 세션으로 바로 진입하므로 관리 비밀번호를 미리 복사할 필요가 없습니다.

프로그램은 누락된 서비스 구성을 생성하고 Codex를 백업한 뒤 연결합니다. 패널에 이미 인계되었다고 표시되면Codex를 다시 시작하고 새 세션을 만든 다음 짧은 메시지를 보내 테스트해야 합니다. 기존 세션은 실시간으로 전환되지 않으므로 기존 세션에서만 계속 테스트하지 마세요.

명령줄로 시작

릴리스 패키지에 시작 스크립트가 없으면 프로그램 디렉터리에서 setup을 실행할 수 있습니다. Windows 명령은 다음과 같습니다.

.\ccodex-sleep-state.exe setup

macOS 명령은 다음과 같습니다.

./ccodex-sleep-state setup

setup은 누락된 구성을 생성하고 서비스를 시작한 뒤 패널을 엽니다. 이미 저장된 구독 및 프록시 설정은 초기화하지 않습니다. 이전 버전에서 이 명령을 지원하지 않으면 먼저 최신 Release로 업그레이드해야 합니다.

브라우저가 자동으로 열리지 않으면 터미널 출력에 따라 관리 주소에 수동으로 접속합니다. 기본 주소는 http://127.0.0.1:17841/admin/이며, 터미널에 표시된 이번 관리 비밀번호를 붙여 넣습니다.

시작 프로그램 자체는 모델 요청을 보내지 않지만 Codex에 연결한 후 state를 수집하는 과정에서 실제 사용량이 소모될 수 있습니다. 서비스 실행 중에는 터미널 창을 열어 두어야 합니다.

첫 연결 완료

패널의 “사용 시작” 영역으로 이동하여 구성 상태가 인계 완료로 표시되는지 확인합니다.
프록시가 감지되지 않으면 “구독 및 프록시”를 열고 로컬 HTTP, HTTPS 또는 SOCKS5 주소를 입력하거나 원격 구독 및 로컬 구독 파일을 가져옵니다.
“연결 설정”에서 모델 및 계정 규칙을 확인합니다.
필요에 따라 “turn-state 주입”에서 주입을 켜거나 끕니다.
Codex를 다시 시작하고 완전히 새로운 세션을 만듭니다.
짧은 메시지를 보낸 다음 패널로 돌아가 요청 횟수, 세션 및 수집 진단 정보를 확인합니다.

처음 실행할 때 명시적인 대체 정책이 설정되어 있지 않으면 setup은 기본적으로 “state를 수집하지 못하면 정상 전달”을 사용합니다. 이전에 엄격 모드를 명시적으로 선택했다면 해당 선택은 계속 유지됩니다.

홈페이지의 “한 번에 Codex 연결”은 주로 연결을 다시 확인하고 복구하는 기능이며, 매번 시작할 때 반드시 클릭해야 하는 것은 아닙니다. 기존 프록시, 구독, 모델 및 주입 스위치도 유지됩니다.

turn-state, 292 및 332 이해하기

이 도구는 업스트림 응답의 X-Codex-Turn-State에 주목합니다. 후보 출구에서 짧은 요청을 보내 state의 형식, 시간 및 암호문 블록 수를 확인하고, 현재 경험적 규칙에 맞는 값을 저장합니다. 이후 요청에는 해당 값이 포함되며 그 값에 대응하는 출구가 사용됩니다.

개인 계정 규칙: 프로젝트에서 허용하는 경험적 형태는 10개 블록, 일반적으로 292자입니다. 11개 블록 또는 312자는 적합한 값으로 처리하지 않습니다.
Team 또는 Business 규칙: 프로젝트에서 허용하는 경험적 형태는 12개 블록, 일반적으로 332자입니다. 13개 블록 또는 356자는 적합한 값으로 처리하지 않습니다.

이러한 길이는OpenAI가 공식적으로 발표한 품질 지표가 아닙니다. 길이가 일치한다고 해서 모델이 이른바 “최상의 상태”라고 증명되는 것은 아니며, 일치하지 않는다고 해서 프록시 손상이나 모델 품질 저하를 단독으로 증명할 수도 없습니다.

자동 인식은 현재 요청의 요금제 표시를 참고하며 길이만으로 계정을 Team으로 판단하지 않습니다. 표시가 명확하지 않으면 패널에 적용된 규칙이 표시됩니다. 개인 또는 Team을 수동으로 지정할 수도 있습니다.

엄격 모드 또는 일반 전달 대체 선택

엄격 모드

엄격 모드는 적합하지 않은 state를 사용하지 않습니다. 수집에 실패하면 명확한 원인을 반환합니다. 사용자가 이미 strict를 명시적으로 선택한 경우 이후 setup을 실행해도 자동으로 덮어쓰지 않습니다.

일반 전달 대체

일반 전달 대체는 사용 가능한 state가 없을 때 주입을 중지하지만, 선택된 출구를 사용하여 정식 요청을 계속 전달합니다. 정식 요청은 최대 한 번만 전달되며, 상태 정보에는 이번 요청에 주입이 없었다는 사실이 명확히 표시됩니다. 수집에 성공한 것처럼 위장하지 않습니다.

이 모드는 속도 제한을 해제하는 것이 아닙니다. 401, 403 또는 429가 발생하면 서비스는 계속 중지 규칙을 따릅니다. 업스트림으로 이미 전송된 정식 생성 요청은 출구를 변경한 후 자동으로 재생되지 않습니다.

프록시 및 구독 구성

프록시 소프트웨어가 이미 설치되어 있다면 “구독 및 프록시” 페이지에서 로컬 HTTP, HTTPS 또는 SOCKS5 주소를 입력할 수 있습니다. 최초 자동 연결은 127.0.0.1의 일반적인 SOCKS5 포트만 확인하며, 로컬 네트워크를 검색하거나 프록시 소프트웨어의 계정 데이터베이스를 읽지 않습니다.

프로젝트는 Clash/Mihomo YAML, 줄 단위 URI 및 Base64 URI 구독도 지원합니다. 내장 출구 어댑터에는 AnyTLS, SS, SSR, VMess, VLESS, Trojan, Hysteria, Hysteria2 및 TUIC가 포함되지만 구독의 TUN, DNS 또는 시스템 규칙은 가져오지 않습니다.

“라우팅” 페이지에서 연결을 테스트하거나 출구를 고정하거나 자동 선택으로 복원할 수 있습니다. 연결 테스트 성공은 네트워크 경로를 사용할 수 있다는 뜻일 뿐, 적합한 state가 이미 수집되었다는 뜻은 아닙니다.

CCS 및 중계 서비스와 함께 사용

공식 ChatGPT 로그인의 경우 도구가 state를 수집하고 주입할 수 있으며 주입을 끌 수도 있습니다. OpenAI 공식 API key의 경우 API 채널을 통해 전달하며 ChatGPT 구독 로그인으로 처리하지 않습니다.

Responses 중계 또는 CCS API key의 경우 도구는 기존 업스트림 및 API key 인증 방식을 유지합니다. 중계 서비스에 공식 로그인 자격 증명을 보내지 않으며 공식 state도 주입하지 않습니다.

CCS가 실제로 provider, 업스트림 또는 인증 방식을 전환하면 서비스는 자격 증명을 잘못된 대상으로 보내지 않도록 전달을 중지합니다. 다음 순서로 전환하는 것을 권장합니다.

ccodex-sleep-state를 중지합니다.
CCS에서 구성을 전환합니다.
ccodex-sleep-state를 다시 시작합니다.
Codex를 다시 시작하고 새 세션을 만듭니다.

구성 충돌이 발생하면 트랜잭션 파일을 삭제하거나 TOML을 무작정 수동 편집하지 마세요. “구성 확인 및 복구”로 이동하여 먼저 변경 사항을 미리 보고, CCS의 현재 구성을 우선 보존한 뒤 다시 인계해야 합니다.

서비스 중지 및 구성 복원

서비스 실행 중에는 터미널 창을 열어 두어야 합니다. 종료하려면 터미널에서 Ctrl+C를 누르고 구성 복원이 완료될 때까지 기다린 다음 Codex를 다시 시작합니다.

브라우저 닫기, state 주입 끄기 및 서비스 중지는 서로 다른 작업입니다. 브라우저를 닫아도 백그라운드 서비스는 중지되지 않으며, 주입을 꺼도 요청 전달은 계속될 수 있습니다. 서비스 프로세스를 종료해야만 중지 및 구성 복원 절차가 시작됩니다.

일반적인 문제 해결

패널에 “인계되지 않음”이 표시됨

서비스가 시작되었다고 해서 Codex 연결이 완료된 것은 아닙니다. 패널의 구성 안내에 따라 처리하고 읽기 전용 --no-config 모드를 사용하고 있지 않은지 확인합니다.

Codex는 응답하지만 패널에 요청이 없음

먼저 Codex를 다시 시작하고 새 세션을 만듭니다. 그래도 기록이 없으면 Codex가 다른 구성, profile, 프로젝트 또는 작업 수준 덮어쓰기를 사용하고 있는지, 혹은 다른 인스턴스가 동시에 실행 중인지 확인합니다.

codex_config_changed 또는 409 발생

“구성 확인 및 복구”를 열고 차이를 미리 본 다음 CCS의 현재 구성을 우선 보존하고 다시 인계합니다.

state_unavailable 또는 로컬 503 발생

계정 규칙, 수집 진단 및 대기 시간을 확인합니다. 먼저 사용을 복구해야 한다면 일반 전달 대체를 명시적으로 선택하거나 일시적으로 주입을 끕니다.

state_shape_changed 발생

state의 형태가 현재 규칙과 일치하지 않는다는 뜻입니다. 정식 요청에서 이미 사용량이 소모되었을 수 있으며 서비스는 자동으로 재생하지 않습니다. 계정 규칙, 업스트림 및 최근 변경 사항을 확인해야 하며 길이 규칙만 단순히 수정해서는 안 됩니다.

415 발생

최신 버전은 공식 클라이언트의 gzip 및 zstd 요청 인코딩을 지원합니다. 이전 버전이 실행 중이지 않은지 확인한 다음 비식별화된 진단 정보를 확인합니다.

502, 503 또는 시간 초과 발생

프록시 출구와 업스트림 서비스 상태를 확인합니다. 네트워크 장애는 state 길이를 수정해 해결할 수 없습니다.

401, 403 또는 429 발생

각각 로그인 상태, 접근 권한 또는 속도 제한이 풀릴 때까지의 대기 상태를 확인합니다. 프로젝트는 IP를 계속 전환하여 이러한 중지 조건을 우회하지 않습니다.

구성 파일 손상

서비스 JSON이 손상되면 setup이 읽기 전용 복구 패널을 엽니다. 백업을 확인한 후 다시 생성하고 재시작합니다. Codex TOML이 손상된 경우 먼저 백업을 보존한 다음 명확한 재생성 절차를 사용하거나 CCS에서 다시 생성하도록 해야 합니다. 손상된 파일에서 API key를 추측하지 마세요.

doctor로 진단 정보 수집

유지 관리자, 커뮤니티 구성원 또는 AI Agent에게 문제 해결 정보를 제공하기 전에 Windows 사용자는 다음을 실행할 수 있습니다.

.\ccodex-sleep-state.exe doctor

macOS 사용자는 다음을 실행합니다:

./ccodex-sleep-state doctor

문제 신고 시에는 일반적으로 운영 체제, Codex 버전, 도구 버전, 오류 메시지와 필요한 범위에서 민감 정보를 제거한 진단 정보만 제공하면 됩니다. auth.json, 관리자 비밀번호, 전체 구독 링크, 계정 자격 증명 또는 전체 데이터 디렉터리는 보내지 마세요.

고급 사용 팁

실제 구성 디렉터리 확인

CODEX_HOME을 설정한 경우 도구는 해당 위치를 따릅니다. 또한 CCODEX_STATE_HOME과 --data-dir도 지원합니다. 현재 어떤 구성 파일을 사용하는지 확실하지 않다면 다음을 실행하세요:

ccodex-sleep-state paths

디렉터리 이름만 보고 현재 구성 위치를 추측하지 마세요.

수집 비용과 쿨다운 이해

state 수집에는 실제 사용량이 발생합니다. 기본적으로 매 라운드마다 후보 출구를 최대 6개까지 시도하며, 단일 탐색에는 최대 20초가 걸리고 두 수집 라운드 사이에는 최소 180초의 간격이 필요합니다. 일반 생성 요청은 자동으로 재생되지 않으므로 수집이나 출구 전환을 비용 없는 재시도로 간주하지 마세요.

모델 및 계정별 격리

Astra, Sol, Terra 간에 state를 재사용하지 마세요. 기본 모델을 변경한 후에는 Codex를 재시작하거나 새 세션을 만들어야 합니다. 모델을 실제로 호출할 수 있는지는 여전히 계정 권한과 upstream에서 해당 모델을 제공하는지 여부에 따라 결정됩니다.

압축 지원은 신중하게 판단

프로젝트 기록에 따르면 실제 Sol의 최신 V2 원격 압축 및 압축 후 이어서 응답하는 기능은 성공했지만, 구형 V1 직접 연결 방식은 upstream에서 404를 반환했습니다. 전송 전 브리지는 로컬 모의 클라이언트 테스트만 완료했으며, 실제 추가 검수에서는 출구 전송 실패도 발생한 적이 있습니다. 따라서 모든 압축 방식이 정상 작동한다고 간주해서는 안 됩니다.

중요한 제한 사항 및 보안 경계

현재 지원되는 모델은 gpt-6-astra, gpt-5.6-sol, gpt-5.6-terra뿐입니다.
현재 Responses HTTP와 SSE를 사용하며, WebSocket은 지원하지 않고 임의의 프로토콜 변환도 제공하지 않습니다.
도구가 계정 대신 모델 권한을 활성화하거나 모델을 자동으로 바꾸지는 않습니다.
시스템 프록시를 전환하거나 Codex 로그인을 갱신하지 않으며, 리셋 카드도 사용하지 않습니다.
중계 서비스에 연결할 수 있다고 해서 turn-state 방식이 해당 중계 서비스에서도 유효하다는 의미는 아닙니다.
인증 값과 전체 state는 일반 로그에 기록되지 않으며, 프로젝트에는 텔레메트리가 없고 로그를 작성자에게 업로드하지도 않습니다.
로컬 프록시 구성과 복구 백업에는 여전히 민감한 정보가 포함될 수 있으므로 직접 안전하게 보관해야 합니다.

개발자 정보

이 프로젝트는 Go로 작성되었으며, 정적 관리 페이지가 바이너리에 포함되어 있어 별도의 프런트엔드 서비스를 시작할 필요가 없습니다. 주요 코드 구조는 다음과 같습니다:

cmd/ccodex-sleep-state: 명령, 원클릭 진입점 및 진단.
internal/codexconfig: provider 구문 분석, 구성 인계, 의미 검사 및 복구 가능한 수정.
internal/gateway: 모델 및 계정 격리, 수집, 압축 및 스트리밍 전달.
internal/turnstate: state 캡슐화 규칙, 현재 값 및 대체 값.
internal/proxyroute: 구독 분석 및 아웃바운드 연결.
internal/service: 단일 인스턴스, 웹 패널, 구성 핫스위칭 및 요청 진단.

프로젝트는 GPL-3.0 라이선스를 따르며, 프록시 부분에는 Mihomo를 재사용합니다. 이 프로젝트는 OpenAI, Mihomo, GPT-Load와 어떠한 제휴 관계도 없습니다.

요약

ccodex-sleep-state의 핵심 가치는 속도 제한 해제나 모델 품질 복구를 약속하는 데 있지 않습니다. Codex 연결, 프록시 출구, turn-state, 구성 백업 및 오류 진단을 확인하고 점검하며 복구할 수 있도록 만드는 데 있습니다. 처음 사용할 때는 먼저 기본 Codex가 정상 작동하는지 확인한 다음 setup을 실행하고, 패널에서 인계 상태를 확인한 뒤 Codex를 재시작하고 새 세션을 만드세요. 문제가 발생하면 우선 패널 진단을 확인하고 doctor를 실행하세요. 구성을 무작정 수정하거나 민감한 자격 증명을 노출하지 마세요.