🌉 Chat2Agent

Набор мостов с открытым исходным кодом, дающий веб-версии ChatGPT возможность работы с локальным рабочим пространством через официальный MCP

💡 Основное назначение Основная цель проекта: дать веб-версии ChatGPT (включая бесплатную и платную версии) возможность напрямую подключаться к локальному рабочему пространству через официальный MCP (Model Context Protocol) коннектор от OpenAI, получая возможности уровня Codex Agent: поиск по коду, изменение файлов, выполнение тестов и проверку кода.

Полные границы проектирования см. в 📑 ADR 0001: Web Agent Boundary и 🗺️ дорожной карте продукта.

🛡️ Нулевая стоимость и абсолютная гарантия безопасности

1. 💰 100% бесплатно, обычный бесплатный аккаунт сразу в деле

• Работает с бесплатной версией ChatGPT: OpenAI официально открыла в веб-интерфейсе Developer Mode / MCP Connector — обычному бесплатному аккаунту не нужна подписка Plus/Team/Pro, чтобы добавить собственный MCP-коннектор!

• Бесплатный публичный туннель: как встроенный бесплатный тариф ngrok, так и бесплатный туннель Pinggy — всё работает без каких-либо затрат, стабильно соединяя локальную машину с веб-интерфейсом.

2. 🔒 Официальный легальный протокол — абсолютный 0 риск блокировки аккаунта

• Официальный открытый стандарт: полностью основан на официально внедрённом OpenAI стандарте Model Context Protocol (MCP) и стандартном процессе OAuth 2.0.

• Никаких реверс-инжиниринга и теневых методов: никогда не внедряем cookie в веб-страницы, никогда не перехватываем непубличные приватные API, никогда не реверсим токены, никогда не используем запрещённые автоматизированные скрипты-парсеры. Для OpenAI это обычный легальный сторонний стандартный коннектор, полностью соответствующий официальным условиям использования (TOS) — на техническом уровне гарантирован 0 риск блокировки аккаунта.

Related MCP server: codex-chatgpt-bridge

🚀 Почему Chat2Agent? (Ключевые улучшения по сравнению с оригинальной версией)

Этот проект — результат глубокого рефакторинга и эволюции на основе отличной идеи Embracecactus/devspace-mcp-tunnel.

Оригинальная версия автора — в основном простой Bash-скрипт для запуска под Linux (всего 11 файлов). Chat2Agent расширен до 66 файлов, добавлено 6400+ строк кода, встроено 40 автоматических модульных тестов — достигнута промышленная трансформация:

✨ Ключевые возможности и инженерная реализация

🏗️ Принцип работы

 ┌─────────────────┐       HTTPS / OAuth       ┌──────────────┐       loopback        ┌────────────────────────┐
 │  网页版 ChatGPT  │ ───────────────────────▶ │   公网隧道   │ ────────────────────▶ │  DevSpace (127.0.0.1)  │
 └─────────────────┘      (ngrok / Pinggy)     └──────────────┘     (Port: 7676)      └───────────┬────────────┘
                                                                                                  │
                                                                       ┌──────────────────────────┴───────────────┐
                                                                       ▼                                          ▼
                                                          ┌──────────────────────────┐               ┌──────────────────────────┐
                                                          │   允许的本地目录 / Shell   │               │  选定的 AGENTS.md / Skills│
                                                          └──────────────────────────┘               └──────────────────────────┘

• Изолированное прослушивание: DevSpace слушает только локальный loopback-адрес 127.0.0.1:7676 и проводит строгую авторизацию через OAuth (пароль владельца).

• Обратный прокси: туннельный инструмент проксирует публичный HTTPS-трафик на локальный порт 7676.

• Правила конечных точек: URL подключения MCP-клиента — https://<домен-туннеля>/mcp, OAuth issuer берётся из publicBaseUrl (то есть чистый корень домена, без /mcp).

• Ноль глобального загрязнения:

  • Запуск в Windows: обновляется только .mcp.json в каталоге проекта, глобальная конфигурация Codex на машине не изменяется.

  • Скрипт обновления Linux: по умолчанию не изменяет ~/.codex/config.toml, синхронизация только при явном добавлении --sync-codex для обратной совместимости.

🌐 Руководство по бесплатной настройке ngrok (пошагово, бесплатно)

Рекомендуется использовать бесплатный ngrok для стабильного публичного туннеля (полностью бесплатно):

1. Регистрация аккаунта: посетите официальный сайт ngrok (ngrok.com) и бесплатно зарегистрируйте аккаунт.

2. Получение Authtoken:

   • После входа перейдите в ngrok Dashboard -> Your Authtoken.

   • Скопируйте сгенерированный токен.

3. （Настоятельно рекомендуется）Получите 1 бесплатный статический домен:

   • В левом меню нажмите Cloud Edge -> Domains.

   • Нажмите Claim a domain, чтобы бесплатно получить собственный статический домен (например, your-name.ngrok-free.app).

   • Преимущество: с фиксированным доменом при каждом перезапуске сервиса не нужно обновлять URL в веб-версии ChatGPT!

4. Заполнение конфигурации проекта:

   • В корневом каталоге проекта скопируйте файл конфигурации:

     Copy-Item .env.example .env.local

   • Отредактируйте .env.local, заполнив только что полученную информацию:

     NGROK_AUTHTOKEN=你的ngrok_authtoken
     NGROK_DOMAIN=your-name.ngrok-free.app # 如果没有申请固定域名则留空

🚀 Быстрый старт в Windows (рекомендуется)

1. Установка зависимостей и инициализация DevSpace

Требования: Node.js >=22.19 <27

# 1. 全局安装 DevSpace CLI 并安装项目依赖
npm install --global @waishnav/devspace
npm ci

# 2. 初始化 DevSpace 配置
devspace init

devspace init проведёт вас через ввод разрешённых каталогов, порта (укажите 7676) и публичного base URL (можно сначала указать https://placeholder.invalid — запускатель автоматически перезапишет).

# 目录授权示例（按需开放）：
D:/AI/project-one,D:/AI/project-two

# 明确接受风险后，也可以全盘开放：
C:/,D:/

2. Запуск одним нажатием, просмотр статуса и остановка

# 运行启动前预检
npm run preflight

# 启动后台受管服务（通过 /healthz 门控后返回成功）
./start.bat

# 查看运行状态与诊断
npm run status

# 精准停止受管进程树
./stop.bat

🐧 Быстрый старт в Linux / WSL

1. Установка и инициализация

git clone https://github.com/xiaoxiao341/Chat2Agent.git
cd Chat2Agent
chmod +x setup.sh refresh-devspace-mcp.sh

# 国内网络建议追加 --mirror 加速 npm 安装
./setup.sh --mirror

2. Запуск туннеля и автоматическая синхронизация

# 方式 A：使用 Pinggy 隧道（默认无需配置任何账号）
./refresh-devspace-mcp.sh --tunnel-cmd "ssh -o StrictHostKeyChecking=no -o UserKnownHostsFile=/dev/null -p 443 -R0:localhost:7676 a.pinggy.io"

# 方式 B：使用 ngrok
./refresh-devspace-mcp.sh --tunnel-cmd "ngrok http 7676" --url-regex 'https://[a-z0-9-]+\.ngrok-free\.app'

# 方式 C：使用已有的公网隧道地址
./refresh-devspace-mcp.sh --known-url "https://abc-123.ngrok-free.app/mcp"

📱 Конфигурация клиента и авторизация

Настройка веб-версии ChatGPT (поддерживает бесплатные аккаунты)

1. Откройте веб-версию ChatGPT, нажмите на аватар в левом нижнем углу: Settings → Apps & Connectors → Advanced → Developer Mode.

2. Нажмите Create connector и укажите ваш публичный MCP-адрес: https://<ваш-домен-туннеля>/mcp.

3. В появившемся окне OAuth введите пароль владельца DevSpace (хранится в ~/.devspace/auth.json) для завершения авторизации.

4. Начните новый диалог, нажмите на значок коннектора на панели инструментов — и ChatGPT сможет читать, писать и запускать ваш локальный код!

🛠️ Диагностический набор и команды CLI

В этом репозитории встроен полный набор диагностических и операционных команд:

# 🔍 综合诊断与能力探针
npm run probe                         # 完整 OAuth + tools/list 诊断
node mcp-probe.mjs --workspace D:/AI/x --json  # 输出 Skills、Subagents 与指令清单
node mcp-probe.mjs --test-delete --test-dir D:/AI/tmp # 安全沙箱删除测试
npm run probe:accept                  # 隔离式编辑、测试、长进程与 diff 自动验收
npm run doctor:web                    # ChatGPT 网页 Connector 专用深度排错

# 📦 资源与 Hook 审计
npm run resources                     # 查看已发现/显式选择的 Codex Skills
npm run hooks                         # 检查网页兼容 Hook（明确标注不支持 before_tool）

# 🔐 OAuth 审计与令牌管控
npm run oauth:list                    # 列出所有已注册的客户端
node oauth-admin.mjs prune            # 清理过期的访问令牌
node oauth-admin.mjs revoke-client <client-id> --yes # 撤销指定客户端
node oauth-admin.mjs revoke-all --yes # 全局吊销所有授权令牌

📂 Структура проекта и описание файлов

├── 🪟 Windows 受管核心
│   ├── start.bat / stop.bat          # Windows 快捷启停入口
│   ├── start-ngrok.mjs               # ngrok 隧道守护与 DevSpace 进程生命周期管理
│   ├── stop-service.mjs              # 基于 PID 树与进程签名的精准安全停止
│   └── service-status.mjs            # 进程状态诊断与健康探测
├── 🐧 Linux / WSL 工具
│   ├── setup.sh                      # 依赖安装与交互初始化
│   ├── refresh-devspace-mcp.sh       # 隧道刷新与配置原子重载
│   └── linux-process-utils.sh        # Linux /proc 标识安全验证与进程管理
├── 🔍 诊断与验收体系
│   ├── web-doctor.mjs                # 网页 Connector 诊断套件
│   ├── mcp-probe.mjs                 # MCP 协议与能力边界探针
│   ├── execution-evidence.mjs        # 隐私最小化执行证据收录
│   └── web-acceptance.mjs            # 真实 ChatGPT 网页交互验收工具
├── 🔐 权限与资源配置
│   ├── oauth-admin.mjs / oauth-db.mjs # OAuth 数据库管理与 Token 撤销
│   ├── resource-admin.mjs            # Codex Skills 与 AGENTS.md 资源镜像
│   └── hook-admin.mjs                # after_tool / tool_failure Hook 适配器
└── 📄 模板与规范
    ├── .env.example                  # 环境变量模板
    ├── .mcp.json.example             # MCP 客户端配置示例
    ├── review.sh / templates/        # 静态审查脚手架与报告模板
    └── docs/                         # ADR 决策记录、路线图与验收报告

💡 Записи о проблемах (Troubleshooting)

• Проявление ошибки: клиент сообщает expected .../ , received .../mcp.

• Анализ причины: в config.json поле publicBaseUrl заполнено адресом с /mcp. DevSpace выводит OAuth issuer из publicBaseUrl, затем добавляет /mcp как конечную точку MCP.

• Решение: убедитесь, что publicBaseUrl — это чистый корень домена (без суффикса), /mcp указывается только в URL подключения на стороне клиента. Скрипты этого проекта автоматически исправляют это.

• Проявление ошибки: команда не найдена в неинтерактивной среде, или у npm-симлинка нет прав на выполнение.

• Решение: скрипты запуска этого проекта автоматически дополняют PATH и содержат встроенную логику самовосстановления chmod +x. Для ручного исправления выполните:

  chmod +x $(readlink -f $(which devspace))

• Анализ причины: традиционный pkill -f сопоставляет аргументы командной строки текущего скрипта, что приводит к ошибочному завершению.

• Решение: этот проект записывает PID и использует идентификатор запуска Linux /proc / цепочку принадлежности процессов Windows для точного завершения.

• Анализ причины: setsid не может напрямую вызывать встроенную команду Shell eval.

• Решение: единообразно обёрнуто в вызов setsid bash -c "$CMD".

• Анализ причины: вышестоящий DevSpace по умолчанию монтирует полное MCP-приложение при вызове таких инструментов, как open_workspace, что приводит к частому созданию iframe; кроме того, исходный компонент зависит от загрузки ресурсов из ngrok, которые блокируются страницей безопасности бесплатного туннеля.

• Решение: этот проект выполняет адаптацию совместимости модуля в памяти:

  1. UI-ресурсы монтируются только для финального show_changes;

  2. используется полностью автономный и версионированный встроенный Diff-компонент (ui://devspace/diff-card-inline-v3.html);

  3. после изменений нажмите Refresh в настройках Connector в ChatGPT и начните новый диалог для тестирования.

• Пояснение: если не настроить фиксированный домен, при каждом перезапуске бесплатного туннеля домен может меняться. Рекомендуется бесплатно получить 1 статический домен в ngrok Dashboard — это решит проблему раз и навсегда, без повторного обновления конечной точки ChatGPT.

🛡️ Правила безопасности и отказ от ответственности

1. Изоляция учётных данных: строго запрещено загружать .env.local, ~/.devspace/auth.json, журналы выполнения или реальный .mcp.json в любой публичный репозиторий.

2. Контролируемый риск: публичный туннель доступен извне — включайте его только при необходимости; при подозрении на утечку учётных данных немедленно выполните node oauth-admin.mjs revoke-all --yes и ротируйте токены.

3. Примечание о лимитах: You've hit your usage limit — это лимит вызовов моделей на стороне OpenAI / ChatGPT и не связано с локальным туннелем или этим проектом.

4. Подробную модель угроз и инструкции по реагированию на инциденты безопасности см. в 🔒 SECURITY.md.

🤝 Благодарности и лицензия (Credits & License)

Этот проект продолжает рефакторинг и эволюцию на основе отличной идеи Embracecactus/devspace-mcp-tunnel.

• Репозиторий оригинального автора: Embracecactus/devspace-mcp-tunnel (благодарность оригинальному автору за прототип Linux-скриптов и практические идеи)

• Базовая поддержка: DevSpace (@waishnav/devspace)

• Лицензия: этот проект полностью открыт под MIT License. В соответствии с требованиями MIT, проект полностью сохраняет уведомление об авторских правах оригинального автора (Copyright (c) 2026 Embracecactus). Вы можете свободно изучать, модифицировать и распространять при соблюдении законности.