ChatGPT Codex Bridge

简体中文 | Безопасность | Вклад

Локальный MCP-мост, который позволяет ChatGPT просматривать зарегистрированные проекты Codex, читать историю сессий Codex и отправлять подтверждённые задачи в локальный CLI Codex.

[!IMPORTANT] Это независимый общественный проект. Он не является официальным продуктом OpenAI и не связан с OpenAI и не одобрен им. ChatGPT, Codex и OpenAI являются товарными знаками их соответствующих владельцев.

Что он делает

• Обнаруживает проекты, уже зарегистрированные в Codex Desktop, не предоставляя доступ ко всему домашнему каталогу.

• Выполняет анализ и планирование в песочнице Codex только для чтения.

• Требует кратковременный одноразовый токен подтверждения перед записью в рабочую область.

• Перечисляет и читает видимые сессии Codex с курсорной пагинацией и редактированием.

• Создаёт ограниченный контекст истории проекта без загрузки многогигабайтных историй в память.

• Создаёт и продолжает постоянные сессии Codex Desktop через локальный протокол app-server Codex.

• Передаёт контекст от ChatGPT в Codex как ненадёжный справочный текст с обнаружением секретов.

• Использует фоновые задания, чтобы длительные задачи Codex не удерживали запрос MCP-туннеля открытым.

Мост не предоставляет произвольный shell-инструмент и не слушает публичный порт. Удалённый доступ обеспечивается официальным клиентом OpenAI Secure MCP Tunnel.

Архитектура

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, прежде чем они появятся на боковой панели.

Требования

• macOS или Linux с Python 3.11+

• Рабочая установка и вход в CLI codex

• Codex Desktop для автоматического обнаружения проектов и функций истории сессий

• Homebrew для документированного пути установки Tunnel

• Доступ организации OpenAI к Secure MCP Tunnels

Этот проект в настоящее время тестируется на macOS. Windows не поддерживается, поскольку необязательный путь уведомлений Desktop использует Unix-сокеты.

Быстрый старт

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. Официальное руководство по подключению Tunnel является источником истины для ролей организации, идентификаторов туннелей, ключей выполнения и текущих команд: openai/tunnel-client/docs/onboarding.md.

Не используйте административный ключ для долго работающего рантайма. Не коммитьте ключи выполнения, идентификаторы туннелей, сгенерированные профили, 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 и применяются при запуске. Важные значения по умолчанию включают два параллельных задания, 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.