ChatGPT Codex Bridge

简体中文 | Security | Contributing

로컬 우선 MCP 브리지로, ChatGPT가 등록된 Codex 프로젝트를 검사하고 Codex 세션 기록을 읽으며 확인된 작업을 로컬 Codex CLI에 전달할 수 있게 해줍니다.

[!IMPORTANT] 이 프로젝트는 독립적인 커뮤니티 프로젝트입니다. 공식 OpenAI 제품이 아니며 OpenAI와 제휴하거나 보증하지 않습니다. ChatGPT, Codex, OpenAI는 해당 소유자의 상표입니다.

기능

• 홈 디렉터리 전체에 대한 접근 권한을 부여하지 않고 Codex Desktop에 이미 등록된 프로젝트를 검색합니다.

• Codex 읽기 전용 샌드박스에서 분석과 계획을 실행합니다.

• 작업공간 쓰기 전에 단기 유효한 일회용 확인 토큰을 요구합니다.

• 커서 페이지네이션과 편집(redaction)을 통해 표시 가능한 Codex 세션을 나열하고 읽습니다.

• 수 기가바이트에 달하는 기록을 메모리에 로드하지 않고 제한된 프로젝트 기록 컨텍스트를 구성합니다.

• 로컬 Codex 앱-서버 프로토콜을 통해 영구 Codex Desktop 세션을 생성하고 이어갑니다.

• ChatGPT가 제공한 컨텍스트를 신뢰할 수 없는 참조 텍스트로 Codex에 전달하며, 비밀 탐지를 수행합니다.

• 백그라운드 작업을 사용하여 긴 Codex 작업이 MCP 터널 요청을 오래 붙잡지 않도록 합니다.

이 브리지는 임의의 셸 도구를 노출하지 않으며 공용 포트에서 수신 대기하지 않습니다. 원격 접근은 공식 OpenAI Secure MCP Tunnel client를 통해 제공됩니다.

아키텍처

flowchart LR
    A[ChatGPT] -->|MCP connector| B[OpenAI Secure MCP Tunnel]
    B -->|outbound tunnel| C[tunnel-client on your machine]
    C -->|stdio MCP| D[ChatGPT Codex Bridge]
    D -->|sandboxed commands| E[Codex CLI]
    D -->|read-only indexes| F[Codex projects and sessions]
    D -. optional local IPC .-> G[Codex Desktop sidebar refresh]

선택적 사이드바 새로고침 경로는 비공개이며 지원되지 않는 Codex Desktop 확장에 의존하므로 이 저장소에 포함되지 않습니다. 핵심 브리지는 이 기능 없이도 작동합니다. 새로 생성된 영구 세션은 사이드바에 나타나기 전에 Codex Desktop을 다시 시작해야 할 수 있습니다.

요구 사항

• Python 3.11+가 설치된 macOS 또는 Linux

• 작동하는 codex CLI 설치 및 로그인

• 자동 프로젝트 검색 및 세션 기록 기능을 위한 Codex Desktop

• 문서화된 Tunnel 설치 경로를 위한 Homebrew

• Secure MCP Tunnels에 대한 OpenAI 조직 액세스 권한

이 프로젝트는 현재 macOS에서 테스트되었습니다. 선택적 Desktop 알림 경로가 Unix 소켓을 사용하므로 Windows는 지원되지 않습니다.

빠른 시작

git clone https://github.com/AaAndrew233/chatgpt-codex-bridge.git
cd chatgpt-codex-bridge
./scripts/bootstrap.sh

bootstrap.sh는 로컬 가상 환경을 생성하고 검토된 의존성 잠금 파일을 설치하며 추적되지 않는 config.json 및 .mcp.json 파일을 생성합니다. 기존 구성을 덮어쓰지 않습니다.

config.json을 열고 인증 소스 하나를 선택합니다:

{
  "codex_command": "codex",
  "model": null,
  "codex_project_catalog": "~/.codex/.codex-global-state.json",
  "allowed_roots": []
}

• model을 null로 유지하여 현재 Codex 구성을 상속합니다.

• allowed_roots를 비워 두면 Codex Desktop에 등록된 프로젝트만 사용합니다.

• 자동 검색을 사용할 수 없는 경우에만 좁은 프로젝트 디렉터리를 allowed_roots에 추가합니다.

• / 또는 홈 디렉터리를 절대 승인하지 마세요. 브리지는 둘 다 거부합니다.

로컬 검사를 실행합니다:

./scripts/check_public_release.py
.venv/bin/python -m unittest discover -s tests -v

Secure MCP Tunnel을 통한 연결

공식 클라이언트를 설치합니다:

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

런타임 키를 이 저장소 외부의 파일에 저장하고 권한을 제한합니다:

chmod 600 /ABSOLUTE/PATH/TO/runtime-key

관리형 백그라운드 런타임을 생성합니다. 모든 자리 표시자 값을 교체하세요:

tunnel-client runtimes connect \
  --alias codex-bridge \
  --profile codex-bridge \
  --tunnel-id '<YOUR_TUNNEL_ID>' \
  --runtime-api-key 'file:/ABSOLUTE/PATH/TO/runtime-key' \
  --mcp-command '/ABSOLUTE/PATH/TO/chatgpt-codex-bridge/scripts/run_server.sh'

관리형 런타임이 실행 중이고 정상이며 준비되었는지 확인합니다:

tunnel-client runtimes status codex-bridge --json

그런 다음 ChatGPT 커넥터 설정에서 커넥터를 생성하거나 새로고침합니다. 조직 역할, 터널 ID, 런타임 키 및 현재 명령에 대한 권위 있는 출처는 공식 Tunnel 온보딩 가이드입니다: openai/tunnel-client/docs/onboarding.md.

장기 실행 런타임에는 관리자 키를 사용하지 마세요. 런타임 키, 터널 ID, 생성된 프로필, config.json 또는 .mcp.json을 커밋하지 마세요.

ChatGPT에서 첫 테스트

커넥터를 활성화한 상태로 새 ChatGPT 대화를 시작하고 다음을 요청하세요:

Call codex_status. Show only whether the bridge is healthy, the available tool names,
and the registered project names. Do not modify files.

그런 다음 읽기 전용 작업을 테스트합니다:

Use codex_analyze on <PROJECT_PATH> to summarize the project structure and identify
the three highest-risk areas. Poll the job until it finishes and retrieve every output page.
Do not modify files.

쓰기의 경우 ChatGPT는 먼저 codex_prepare_apply를 호출하고 정확한 계획을 표시하며 명시적 확인을 받은 다음에만 반환된 토큰으로 codex_apply를 호출해야 합니다.

MCP 도구

보안 모델

신뢰 경계는 의도적으로 좁게 설정되어 있습니다:

• 프로젝트 접근은 검증된 Codex 프로젝트 루트 또는 명시적 좁은 루트로 제한됩니다.

• .ssh, .aws, .gnupg, .kube, .config, Library와 같은 민감한 디렉터리는 자동 검색 중에 거부됩니다.

• Codex 하위 프로세스는 최소 환경을 받고 명시적 샌드박스 모드로 실행됩니다.

• 쓰기 토큰은 만료되며 일회용이고 정확한 프로젝트와 요청에 바인딩됩니다.

• 세션 출력은 사용자 표시 메시지로 필터링되고 머신을 떠나기 전에 편집됩니다.

• 요청, 출력, 스캔, 동시성, 보존 및 시간 초과 한도가 제한됩니다.

• ChatGPT 컨텍스트는 신뢰할 수 없는 입력으로 처리되며 로컬 정책을 재정의할 수 없습니다.

브리지를 팀에 노출하기 전에 docs/security-model.md를 읽으세요. 취약점 보고는 SECURITY.md를 따라야 합니다.

운영 한도

기본 한도는 config.example.json에 문서화되어 있으며 시작 시 적용됩니다. 중요한 기본값에는 동시 작업 2개, 완료된 작업 30분 보존, 120,000자 요청 상한, 페이지네이션된 100,000자 작업 출력, 프로젝트 기록에 대한 제한된 스트리밍 스캔이 포함됩니다.

scan_complete는 구성된 소스 스캔이 완료되었는지 여부를 나타냅니다. context_complete는 스캔된 모든 텍스트가 반환된 컨텍스트 예산에 맞는지 여부를 별도로 나타냅니다. 완전한 스캔은 무제한 내보내기와 동일하지 않습니다.

개발

./scripts/bootstrap.sh
.venv/bin/python -m unittest discover -s tests -v
.venv/bin/python -m compileall -q \
  bridge_core.py conversation_catalog.py desktop_assignment.py \
  desktop_sessions.py project_context.py server.py

기여 규칙은 CONTRIBUTING.md를, 모듈 경계는 docs/architecture.md를 참조하세요.

라이선스

Apache License 2.0. LICENSE를 참조하세요.