🌉 Chat2Agent

Open-Source-Brücken-Suite, die der ChatGPT-Weboberfläche über offizielles MCP lokale Arbeitsbereichsfähigkeiten verleiht

💡 Kernpositionierung Das Hauptziel dieses Projekts: Der Webversion von ChatGPT (einschließlich kostenloser und kostenpflichtiger Versionen) soll über den offiziellen MCP-Connector (Model Context Protocol) von OpenAI direkt auf den lokalen Arbeitsbereich zugreifen können – mit Code-Recherche, Dateiänderung, Testausführung und Review-Fähigkeiten wie ein Codex Agent.

Die vollständigen Design-Grenzen finden Sie in 📑 ADR 0001: Web Agent Boundary und der 🗺️ Produkt-Roadmap.

🛡️ Nullkosten und absoluter Sicherheitsschutz

1. 💰 100% kostenlos, normales kostenloses Konto startet direkt durch

• ChatGPT kostenlose Version nutzbar: OpenAI hat im Web Developer Mode / MCP Connector freigeschaltet. Normale kostenlose Konten können ohne Plus/Team/Pro-Abo direkt eigene MCP-Connectors hinzufügen!

• Kostenloser öffentlicher Tunnel: Ob mit dem integrierten ngrok-Kostenlos-Tarif oder dem Pinggy-Kostenlos-Tunnel – ohne jegliche Kosten wird die Kommunikation zwischen lokal und Web stabil hergestellt.

2. 🔒 Offizielles, reguläres Protokoll – absolut 0 Sperrrisiko

• Offizieller offener Standard: Vollständig basierend auf dem von OpenAI offiziell eingeführten Model Context Protocol (MCP)-Standard und dem Standard-OAuth-2.0-Ablauf.

• Keine Reverse-Engineering- oder Black-Hat-Methoden: Niemals Injektion von Web-Cookies, niemals Abgreifen nicht-öffentlicher privater Schnittstellen des Webs, niemals Reverse-Engineering von Tokens, niemals Verwendung irgendwelcher unzulässiger automatisierter Scraper-Skripte. Für OpenAI ist dies ein regulärer Drittanbieter-Standard-Connector, der vollständig den offiziellen Nutzungsbedingungen (TOS) entspricht – technisch von Grund auf 0 Sperrrisiko.

Related MCP server: codex-web-bridge

🚀 Warum Chat2Agent? (Wichtige Upgrades gegenüber der Originalversion)

Dieses Projekt ist eine tiefgreifende Weiterentwicklung auf Basis der hervorragenden Idee von Embracecactus/devspace-mcp-tunnel.

Die Originalversion war hauptsächlich ein einfaches Linux-Bash-Startskript-Demo (insgesamt 11 Dateien). Chat2Agent wurde auf 66 Dateien erweitert, mit 6400+ neuen Codezeilen und 40 integrierten automatisierten Unit-Tests – eine industrielle Transformation:

✨ Kernfunktionen und Hardcore-Engineering-Implementierung

🏗️ Funktionsweise

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

• Isolierte Überwachung: DevSpace überwacht nur die lokale Loopback-Adresse 127.0.0.1:7676 und führt eine strenge Autorisierungsprüfung über OAuth (Owner-Passwort) durch.

• Reverse-Proxy: Das Tunnel-Tool leitet öffentlichen HTTPS-Verkehr an den lokalen Port 7676 weiter.

• Endpunkt-Regeln: Die MCP-Client-Verbindungs-URL lautet https://<Tunnel-Domain>/mcp, der OAuth-issuer stammt aus publicBaseUrl (also der reinen Domain-Wurzel, ohne /mcp).

• Null globale Verschmutzung:

  • Windows-Starter: Aktualisiert nur .mcp.json im Projektverzeichnis, verändert nicht die globale Codex-Konfiguration des lokalen Systems.

  • Linux-Refresh-Skript: Ändert standardmäßig nicht ~/.codex/config.toml, nur bei explizitem Anhängen von --sync-codex als Legacy-Kompatibilitätssynchronisation.

🌐 Kostenloser ngrok-Konfigurationsleitfaden (Schritt für Schritt zum Nulltarif)

Empfohlen wird der kostenlose ngrok für einen stabilen öffentlichen Tunnel (vollständig kostenlos):

1. Konto registrieren: Besuchen Sie die ngrok-Website (ngrok.com) und registrieren Sie sich kostenlos.

2. Authtoken abrufen:

   • Nach dem Login gehen Sie zu ngrok Dashboard -> Your Authtoken.

   • Kopieren Sie den generierten Token.

3. (Stark empfohlen) 1 kostenlose statische Domain beanspruchen:

   • Klicken Sie im linken Menü auf Cloud Edge -> Domains.

   • Klicken Sie auf Claim a domain, um eine exklusive statische Domain kostenlos zu beanspruchen (z. B. your-name.ngrok-free.app).

   • Vorteil: Mit fester Domain müssen Sie die URL nach jedem Neustart des Dienstes nicht erneut in der ChatGPT-Weboberfläche aktualisieren!

4. In die Projektkonfiguration eintragen:

   • Kopieren Sie im Projektstammverzeichnis eine Konfigurationsdatei:

     Copy-Item .env.example .env.local

   • Bearbeiten Sie .env.local und tragen Sie die eben erhaltenen Informationen ein:

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

🚀 Windows-Schnellstart (empfohlen)

1. Abhängigkeiten installieren und DevSpace initialisieren

Umgebungsanforderung: Node.js >=22.19 <27

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

# 2. 初始化 DevSpace 配置
devspace init

devspace init führt Sie durch die Eingabe der erlaubten Verzeichnisse, des Ports (geben Sie 7676 ein) und der öffentlichen Base-URL (kann zunächst https://placeholder.invalid sein, der Starter überschreibt sie automatisch).

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

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

2. Ein-Klick-Start, Status anzeigen und Stoppen

# 运行启动前预检
npm run preflight

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

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

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

🐧 Linux / WSL-Schnellstart

1. Installation und Initialisierung

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

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

2. Tunnel starten und automatisch synchronisieren

# 方式 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"

📱 Client-Konfiguration und Autorisierung

Webversion-ChatGPT-Konfiguration (unterstützt kostenlose Konten)

1. Öffnen Sie die ChatGPT-Weboberfläche, klicken Sie auf das Avatar-Symbol unten links und gehen Sie zu Settings → Apps & Connectors → Advanced → Developer Mode.

2. Klicken Sie auf Create connector und tragen Sie Ihre öffentliche MCP-Adresse ein: https://<Ihre-Tunnel-Domain>/mcp.

3. Geben Sie im erscheinenden OAuth-Fenster das Owner-Passwort von DevSpace ein (gespeichert in ~/.devspace/auth.json), um die Autorisierung abzuschließen.

4. Starten Sie einen neuen Chat und klicken Sie auf das Connector-Symbol in der Symbolleiste – ChatGPT kann jetzt Ihren lokalen Code lesen, schreiben und ausführen!

🛠️ Diagnose-Toolbox und Befehlszeilenbefehle

Dieses Repository enthält eine vollständige Suite von Diagnose- und Betriebsbefehlen:

# 🔍 综合诊断与能力探针
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 # 全局吊销所有授权令牌

📂 Projektstruktur und Dateibeschreibung

├── 🪟 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 决策记录、路线图与验收报告

💡 Fehlerbehebungsprotokoll (Troubleshooting)

• Fehlerbild: Der Client meldet expected .../ , received .../mcp.

• Ursachenanalyse: publicBaseUrl in config.json wurde mit /mcp-Suffix gefüllt. DevSpace leitet den OAuth-issuer aus publicBaseUrl ab und fügt dann /mcp als MCP-Endpunkt an.

• Lösung: Stellen Sie sicher, dass publicBaseUrl die reine Domain-Wurzel ist (ohne Suffix), und nur die vom Client ausgefüllte Verbindungs-URL trägt /mcp. Die Skripte dieses Projekts haben eine automatische Korrektur eingebaut.

• Fehlerbild: Befehl in nicht-interaktiver Umgebung nicht gefunden, oder npm-Symlink ohne Ausführungsberechtigung.

• Lösung: Das Startskript dieses Projekts ergänzt automatisch die PATH-Umgebungsvariable und enthält eine eingebaute chmod +x-Selbstheilungslogik. Für manuelle Reparatur ausführen:

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

• Ursachenanalyse: Das traditionelle pkill -f-Muster kann die eigenen Befehlszeilenargumente des aktuellen Skripts matchen und Schaden verursachen.

• Lösung: Dieses Projekt protokolliert stattdessen die PID und kombiniert Linux-/proc-Startkennungen/Windows-Prozess-Zugehörigkeitsketten für präzise Beendigung.

• Ursachenanalyse: setsid kann den Shell-Builtin-Befehl eval nicht direkt aufrufen.

• Lösung: Einheitlich als setsid bash -c "$CMD"-Aufruf gekapselt.

• Ursachenanalyse: Das Upstream-DevSpace hängt standardmäßig bei Tool-Aufrufen wie open_workspace die vollständige MCP-App ein, was häufige iframe-Erstellung verursacht; außerdem lädt die Originalkomponente Ressourcen von ngrok, die von der Sicherheitsblockierungsseite des kostenlosen Tunnels blockiert werden.

• Lösung: Dieses Projekt führt eine Kompatibilitätsanpassung des Moduls im Speicher durch:

  1. UI-Ressourcen werden nur an das finale show_changes gebunden;

  2. Verwendung einer vollständig eigenständigen und versionierten Inline-Diff-Komponente (ui://devspace/diff-card-inline-v3.html);

  3. Nach der Änderung bitte in den ChatGPT-Connector-Einstellungen auf Refresh klicken und einen neuen Chat zum Testen starten.

• Hinweis: Ohne Konfiguration einer festen Domain kann sich die Domain des kostenlosen Tunnels bei jedem Neustart ändern. Es wird empfohlen, im ngrok-Dashboard kostenlos 1 statische Domain zu beanspruchen – dann müssen Sie den ChatGPT-Endpunkt nie wieder aktualisieren.

🛡️ Sicherheitsrichtlinien und Haftungsausschluss

1. Anmeldedaten-Isolation: Es ist strengstens untersagt, .env.local, ~/.devspace/auth.json, Laufprotokolle oder echte .mcp.json-Dateien in öffentliche Code-Repositories zu committen.

2. Risiko kontrollierbar: Der öffentliche Tunnel ist erreichbar – bitte nur bei Bedarf aktivieren; bei Verdacht auf Anmeldedaten-Leck sofort node oauth-admin.mjs revoke-all --yes ausführen und Tokens rotieren.

3. Kontingent-Hinweis: You've hit your usage limit ist eine Modell-Aufruf-Kontingentbegrenzung auf OpenAI/ChatGPT-Seite und hat nichts mit dem lokalen Tunnel oder diesem Projekt zu tun.

4. Das ausführliche Bedrohungsmodell und die Sicherheitsreaktionshinweise finden Sie in 🔒 SECURITY.md.

🤝 Danksagung und Open-Source-Lizenz (Credits & License)

Dieses Projekt ist eine Weiterentwicklung auf Basis der hervorragenden Idee von Embracecactus/devspace-mcp-tunnel.

• Original-Repository: Embracecactus/devspace-mcp-tunnel (Dank an den Originalautor für die Grundlage des Linux-Automatisierungsskript-Prototyps und die praktischen Ansätze)

• Basis-Unterstützung: DevSpace (@waishnav/devspace)

• Open-Source-Lizenz: Dieses Projekt ist vollständig unter der MIT-Lizenz Open Source. Gemäß den MIT-Lizenzbestimmungen wurde der Copyright-Hinweis des Originalautors (Copyright (c) 2026 Embracecactus) vollständig beibehalten. Sie können das Projekt unter Einhaltung der gesetzlichen Vorschriften frei lernen, modifizieren und weiterverbreiten.