Codex ↔ ChatGPT Bridge: macOS, несколько проектов

Адаптация Zhenyu98/codex-chatgpt-bridge, исходный commit 351c66fef0390872443af1587a978e6f76f479b8. MIT-лицензия сохранена. Оригинальные Windows-скрипты оставлены в skills/.../scripts; macOS использует новый Python-контроллер.

Один bridge обслуживает независимые проекты. ChatGPT проектирует и принимает работу; Codex меняет код и запускает тесты. Проекты не могут иметь одинаковые или вложенные рабочие папки. Один основной Architect thread назначается одному проекту.

Что реализовано и что требует подключения

Реализованы Streamable HTTP MCP, OAuth 2.1/PKCE, изоляция по project scope, безопасное чтение исходников, очередь TASK → Codex → result → ACCEPT/FIX, macOS Keychain, два LaunchAgent одного bridge (MCP и исполнитель), восстановление состояния и явный Off.

Пример профиля iiko: config/iiko-backoffice.example.json. Скопируйте его в config/projects/iiko-backoffice.local.json и заполните собственные пути и ID чатов. Исполнитель запускает отдельные короткие codex exec-сессии в рабочей папке; он не внедряет сообщения в существующий desktop Codex-чат.

Windows: исходный PowerShell/DevSpace workflow описан в README.Windows.md. Принудительный read-only MCP этого fork реализован для macOS; Windows legacy-профиль использует разрешения как политику и не предоставляет ту же техническую границу.

Автоматическая передача данных и автоматическое пробуждение ChatGPT — разные возможности. MCP передаёт задания/результаты без ZIP и копирования файлов, когда Architect обращается к инструментам. Сам сервер не может заставить существующий ChatGPT-чат начать новый ответ. chatgpt_thread хранит привязку для маршрутизации, но не является API для отправки сообщений. Постоянный автономный цикл с пробуждением требует отдельно разрешённого транспорта/доступного механизма уведомлений. Cookies, скрытые ChatGPT API и пароль от аккаунта здесь не используются.

Для облачного ChatGPT потребуется HTTPS endpoint или Secure MCP Tunnel и подключение в интерфейсе ChatGPT. Текущий http://127.0.0.1:8765/mcp предназначен для локальной проверки. Авторизация конкретного чата и публичный туннель не появляются от одного сохранения ID в config.

auto_execute в примерах — false: сначала подключите Architect и проверьте рабочее дерево. Существующие задания продукта не импортируются автоматически. Для продолжения нумерации задайте task_number_start; исходное задание нужно передать через submit_task целиком, а не восстанавливать по названию.

Related MCP server: bothy-board

Установка

git clone https://github.com/DmitriySergeyev88/codex-chatgpt-bridge-win-macos.git
cd codex-chatgpt-bridge-win-macos

Нужны macOS, Python 3.11+, Git, Codex CLI с выполненным codex login и доступ к login Keychain. Проверенная версия Codex CLI — 0.160.0. При существующей авторизации через ChatGPT новый API key не требуется.

cd /absolute/path/to/codex-chatgpt-bridge
cp config/instance.example.json config/instance.local.json
mkdir -p config/projects
cp config/project.example.json config/projects/my-project.local.json
# Отредактируйте оба JSON: реальные абсолютные пути, ID Architect, URL и codex_binary.
./install.sh
.venv/bin/python -m bridge.cli launchd-install
.venv/bin/python -m bridge.cli on
.venv/bin/python -m bridge.cli doctor

Личные конфиги не входят в публичный репозиторий. install.sh создаёт venv и использует зафиксированные версии из requirements.lock. Он не меняет рабочие исходники проекта. launchd-install устанавливает два файла org.codex.ai-bridge.server.plist и org.codex.ai-bridge.executor.plist в ~/Library/LaunchAgents. Они запускаются при входе пользователя и перезапускаются при сбое. Намеренный Off хранится отдельно; при следующем входе агенты не открывают выключенный bridge.

Мастер-ключ шифрования OAuth-state и пароль владельца хранятся в Keychain service org.codex.ai-bridge, accounts <instance_id>:encryption и <instance_id>:owner. В config нет паролей. Секреты не передаются как аргументы subprocess. Доступ к Keychain может запросить системное разрешение для Python.

Подключение ChatGPT

1. Подготовьте стабильный HTTPS-прокси/туннель к 127.0.0.1:8765. Он должен сохранять путь /mcp, OAuth-маршруты и корректный Host. Укажите HTTPS origin без пути в public_base_url, затем выполните reboot. Не направляйте прокси на DevSpace.

2. В developer mode ChatGPT добавьте MCP-подключение с URL https://your-host/mcp, выберите OAuth. SDK публикует discovery metadata, dynamic registration, authorize/token/revoke endpoints.

3. Для пароля владельца выполните в собственном локальном интерактивном терминале .venv/bin/python -m bridge.cli owner-password. Введите пароль только в странице авторизации bridge. Не вставляйте его в чат.

4. При OAuth выберите ровно один проект. Для другого проекта создайте отдельное подключение к тому же bridge и выберите другой project scope. Один сервер обслуживает все подключения; токен одного проекта не открывает другой.

5. В главном Architect-чате включите соответствующий MCP и вызовите project_info, list_files, read_file для README. .env и чужой проект должны возвращать ошибку. Затем включите локально auto_execute: true в профиле проекта и выполните reboot, когда очередь и рабочая папка готовы.

При наличии OpenAI Secure MCP Tunnel можно использовать поддерживаемый OpenAI tunnel-client для доступа к локальному /mcp. Это отдельный транспорт: его tunnel ID, runtime credential и авторизация не поставляются с репозиторием. Совместимость конкретного tunnel auth flow нужно проверить после подключения; локальные тесты не подтверждают её.

Официальная документация: MCP server quickstart, подключение MCP, Secure MCP Tunnel, Codex non-interactive.

Профиль проекта

{
  "bridge_project_id": "OSKZ-IIKO-BACKOFFICE",
  "name": "Сервис AI бэк-офиса iiko",
  "workspace": "/absolute/path/to/iiko",
  "chatgpt_thread": "architect-conversation-id",
  "codex_workspace": "/absolute/path/to/iiko",
  "mode": "CHATGPT_ARCHITECT",
  "chatgpt_access": "READ_ONLY",
  "auto_execute": false,
  "enabled": true,
  "task_number_start": 3,
  "deny_paths": ["ops", "config", "docs/test-results"]
}

В первой версии workspace и codex_workspace должны разрешаться в одну папку — так очередь, исходники и результат не расходятся. Это корень Git-репозитория, не весь домашний каталог. bridge_project_id: 3–64 символа, заглавные латинские буквы, цифры, _ и -, первый символ — буква. deny_paths дополняет встроенный запрет секретов.

chatgpt_thread — назначенный основной чат. MCP не сообщает надёжный conversation ID: сервер принудительно изолирует проект по OAuth scope, но не может доказать, что вызов пришёл именно из записанного чата. Не включайте проектное подключение в другие чаты, которым этот проект не нужен.

При init создаётся:

.ai-bridge/
├── state.json             # читаемая проекция состояния
├── architecture.md        # привязка ролей; действующие спецификации продукта остаются главными
├── tasks/TASK-NNN-Rn.json
├── results/TASK-NNN-Rn.json
├── reviews/TASK-NNN-Rn.json
├── queue.sqlite3          # источник истины и история переходов
├── .executor.lock
└── .export.lock

MCP не предоставляет произвольную запись файлов, включая architecture.md. Этот документ редактирует Codex локально по принятому решению. Для задач/ревью разрешены только структурированные операции, которые записывают фиксированные записи очереди. READ_ONLY означает read-only исходников, а не полный запрет metadata-записей.

Цикл работы

Architect вызывает submit_task(bridge_project_id, title, instructions, acceptance, idempotency_key). Инструкции должны включать полный scope и требования; недоступные ChatGPT-вложения не скачиваются автоматически. Запрос нельзя принять, если предыдущая задача не принята. Повтор с тем же ключом и payload возвращает прежний ответ; другой payload с тем же ключом отклоняется.

Исполнитель забирает QUEUED → RUNNING. Он использует codex exec --sandbox workspace-write, schema для результата и существующую локальную авторизацию Codex. У него отключена пользовательская конфигурация и дополнительные execpolicy rules, нет bypass sandbox; cwd закреплён на проекте. Файлы/тесты/критерии/отклонения возвращаются структурированно. Сырые события не выдаются ChatGPT и удаляются после обычного завершения.

Result сохраняется, успешное исполнение получает AWAITING_REVIEW. Architect через task_result читает отчёт и историю, через read_file/git_diff проверяет фактический код. git_diff показывает tracked-изменения; новые untracked-файлы нужно читать отдельно. Непройденные критерии дают EXECUTION_FAILED: его нельзя принять как успешный.

review_task требует точную revision:

• ACCEPT → ACCEPTED, затем разрешён следующий submit_task.

• FIX → следующая revision той же задачи и QUEUED, инструкции дополнены замечаниями.

• Старое ревью, повторное исполнение с прежним run ID и преждевременная приёмка отклоняются.

Одна задача исполняется в проекте одновременно. Для разных проектов работают отдельные очереди и исполнители; сбой одного не меняет состояние другого. Проверка критериев в result подтверждает полноту отчёта, но статус PASS остаётся утверждением Codex, которое Architect проверяет по коду и свидетельствам. Это не универсальный формальный доказатель корректности.

Для запуска ровно одной уже поставленной задачи локально:

.venv/bin/python -m bridge.cli execute-once OSKZ-IIKO-BACKOFFICE

Добавление проекта

1. Скопируйте config/project.example.json в config/projects/<name>.local.json.

2. Заполните уникальные project ID, Architect thread и реальные пути. Укажите deny_paths, если в проекте есть чувствительные данные вне стандартных мест.

3. Запустите init: он проверит профиль и создаст .ai-bridge, не перезаписывая существующую архитектуру. Дублирующиеся/вложенные workspace и один Architect на два проекта запрещены.

4. Выполните reboot, затем отдельную OAuth-авторизацию нового проекта. При добавлении проекта прежние токены сохраняются, но не получают доступ к новой папке.

5. Поставьте небольшую задачу, проверьте результат и ревью, затем включите auto_execute.

Локальные .local.json, .runtime, Keychain и очереди не включайте в публичный репозиторий. При необходимости добавьте .ai-bridge/ в локальный Git exclude проекта; установщик не изменяет его автоматически.

Восстановление после перезапуска

.venv/bin/python -m bridge.cli status
.venv/bin/python -m bridge.cli doctor
.venv/bin/python -m bridge.cli reboot

on включает желаемое состояние и проверяет /health + отказ неавторизованного /mcp (401). off закрывает локальный сервис, сохраняя OAuth. reboot выполняет остановку/запуск и отказывается менять intentional Off. Занятый чужим процессом порт не приводит к убийству процесса: запуск не проходит проверку/блокировку.

SQLite transactions, fsync и блокировки сохраняют очередь. Если процесс упал между фиксацией состояния и экспортом JSON, повторный init восстановит state.json и остальные проекции из БД. История результатов/ревью прежних revisions сохраняется.

Если Codex был прерван, bridge не запускает задачу повторно автоматически. При исчезнувшем исполнителе статус становится INTERRUPTED. Если дочерний Codex ещё работает, восстановление сохраняет RUNNING; даже возможное повторное использование PID трактуется осторожно. Сначала проверьте живой процесс и рабочий diff, затем:

.venv/bin/python -m bridge.cli recover OSKZ-IIKO-BACKOFFICE
# Только после проверки исходников и отсутствия живого исполнителя:
.venv/bin/python -m bridge.cli retry OSKZ-IIKO-BACKOFFICE TASK-003

Ошибку исполнения можно исправить через Architect FIX или повторить локально после выяснения причины. ACCEPT не выдаёт разрешение на commit/push/install/deploy. Такие действия остаются отдельным поручением человеку/Codex.

Для отзыва OAuth:

.venv/bin/python -m bridge.cli rotate

rotate выключает bridge, удаляет grants и меняет пароль владельца в Keychain. После него требуются on и повторная OAuth-авторизация. Резервируйте queue.sqlite3 через SQLite backup API при работающем процессе; либо остановите bridge и сохраните всю .ai-bridge. Потеря Keychain мастер-ключа означает потерю старой OAuth-state: нужна новая авторизация, очередь задач при этом не теряется.

Удаление LaunchAgents:

.venv/bin/python -m bridge.cli off
launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/org.codex.ai-bridge.server.plist
launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/org.codex.ai-bridge.executor.plist
rm ~/Library/LaunchAgents/org.codex.ai-bridge.server.plist ~/Library/LaunchAgents/org.codex.ai-bridge.executor.plist

Безопасность и DevSpace

У upstream DevSpace есть write_file/edit_file/run_shell. Его уровни разрешений — политика, а не принудительная read-only граница. Поэтому он не используется в открытом Architect-профиле. Совместимый стандарт MCP сохранён через официальный Python SDK; оригинальный DevSpace/Windows workflow сохранён в исходных файлах как отдельный legacy-вариант. Нельзя запускать исходный installer/DevSpace endpoint и считать, что новый read-only профиль его ограничивает.

Публичные инструменты: project_info, list_files, read_file, search_files, git_status, git_diff, submit_task, task_result, review_task. Никаких generic write/shell/install/git commit/push tools. Результат добавляет только локальный Codex executor.

Чтение ограничено типами текстовых исходников/документов. Запрещены .env* (включая example), .git, credentials/secrets/password/token paths, .ssh/.aws, .npmrc, Keychain/runtime, private keys, storage, базы, логи, build/dependency-каталоги, symlinks, hardlinks и специальные файлы. Traversal и абсолютные пути отклоняются; файлы открываются через directory descriptors с O_NOFOLLOW. Поиск — literal, ограничен 100 результатами и 10 000 entries; файл ≤256 KB. Git принимает только фиксированные status/diff без shell, fsmonitor, external diff/textconv и пользовательских flags; чувствительные paths исключены.

Распространённые credential patterns маскируются в содержимом и result. Это дополнительная защита, не доказательство отсутствия произвольного секрета в разрешённом исходнике. Если секрет случайно записан в обычный документ, исключите этот документ через deny_paths и устраните утечку. Codex и bridge работают от одного macOS пользователя: Keychain защищает хранение, но не изолирует уже работающий локальный executor от прав этого пользователя. Для более строгой OS-изоляции нужен отдельный пользователь/VM.

Проверки

.venv/bin/python -m pytest -q

Тесты проверяют project isolation, запрет secrets/traversal/symlink/hardlink/FIFO, подавление external Git diff, идемпотентность, crash recovery, FIX/ACCEPT, следующие задания, реальный HTTP MCP, OAuth/PKCE, replay кода, refresh/revoke и сохранение токенов после реконструкции сервера. Изолированная настоящая Codex-проверка описана отдельно в VALIDATION.md. Она не является product acceptance iiko.