Skip to main content
Glama
deeneskoruzh
xiaoxiao341

Chat2Agent

by xiaoxiao341
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Local

🌉 Chat2Agent

让 ChatGPT 网页端通过官方 MCP 拥有本地工作区能力的开源桥接套件

Node.js License: MIT CI Status Account Safety Cost Upstream Based on DevSpace

💡 核心定位 本项目的主要目标是：让**网页版 ChatGPT（包括免费版及付费版）**通过 OpenAI 官方 MCP (Model Context Protocol) 开发者连接器直接对接本机工作区，获得如同 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、绝不抓取网页非公开私有接口、绝不逆向 Token、绝不使用任何违规自动化爬虫脚本。对于 OpenAI 而言，这就是一个正规的第三方标准连接器，完全符合官方使用条款（TOS），从技术底层确保 0 封号风险。

Related MCP server: codex-chatgpt-bridge

🚀 为什么选择 Chat2Agent？（相比原作者版本的重大升级）

本项目是在 Embracecactus/devspace-mcp-tunnel 优秀创意的基础上进行深度重构演进而来的。

原作者版本主要是 Linux 下的简易 Bash 启动脚本 Demo（共 11 个文件）。Chat2Agent 扩展到了 66 个文件、新增 6400+ 行代码、内置 40 个自动化单元测试，实现了工业级蜕变：

维度

原作者版本 (devspace-mcp-tunnel)

Chat2Agent 增强重构版 (本项目)

跨平台架构

仅支持 Linux/WSL 基础 Bash 运行

原生支持 Windows 企业级受管守护进程（start.bat/stop.bat），同时完美兼容 Linux/WSL

进程生命周期

pkill -f 模糊匹配，易误杀当前脚本或其它 Node

基于 PID 树与 Linux /proc 启动时间戳双重校验，100% 精准启停，杜绝误杀

长进程异步轮询

无进程会话保持，短命令易卡死

实现长任务 Process Session 保持，解决 ChatGPT 丢失 0 序列化 Bug（yieldTimeMs: 1），支持 write_stdin 异步轮询与跨 Session 恢复

启动与恢复健康门控

启动后无探测，不知道服务是否真正可用

同时监测本地与公网 /healthz，休眠或网络中断后自动重建 ngrok 隧道，只有两端均正常才报告就绪

网页 Diff 渲染

使用 DevSpace 原生输出，网页端频繁卡死、白屏

自研版本化内联 Diff 卡片，解决 ngrok 拦截；仅对 show_changes 绑定 UI，告别 iframe 页面卡顿

Codex 资源复用

粗暴读取全局配置或缺乏隔离

实现 Codex 资源只读安全镜像与隔离（ADR 0001），严选 3 大 Skills，绝不污染修改本地全局 Codex

安全沙箱 Hook

无工具拦截审计与安全保护

新增 after_tool/tool_failure 沙箱 Hook 适配器，自动剥离密码/API Key 等敏感环境变量

安全与白名单

粗暴继承全局 * 主机白名单

主动剔除全局通配符，根据公网域名与回环动态派生白名单；凭据由 .env.local 严密保护

OAuth 会话治理

无法管理已授权的客户端与令牌

内置 OAuth 数据库管理工具，支持 Token 过期自动裁剪、按客户端撤销及一键全局吊销

诊断探针工具箱

无配套排错与测试脚本

新增 6 大 CLI 探针（doctor:web 深度诊断、mcp-probe 能力探针、沙箱自动验收测试等）

协议元数据监测

无法感知工具更新与缓存污染

自研版本化 URI 缓存穿透策略（diff-card-inline-v3.html），Doctor 实时检测 ChatGPT 端元数据新鲜度

隐私保护机制

无执行状态审计

Fail-closed 隐私最小化执行证据收集，仅记录退出码，绝不收集用户源码和指令内容

双重真实验收

无验收标准

确立自动化探针与真实网页双重验收体系（npm run accept:web:verify），保证实测可见性

工程与自动化测试

无测试用例

内置 16 个测试套件、40 个单元与集成测试，配备 Windows / Ubuntu 双系统 GitHub Actions CI

✨ 核心特性与硬核工程实现

🏗️ 工作原理

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

  • 隔离监听：DevSpace 仅监听本机回环地址 127.0.0.1:7676，并通过 OAuth（Owner 密码）进行严格的授权审批。

  • 反向代理：隧道工具将公网 HTTPS 流量代理至本地 7676 端口。

  • 端点规则：MCP 客户端连接 URL 为 https://<隧道域名>/mcp，OAuth issuer 来自 publicBaseUrl（即纯域名根，不带 /mcp）。

  • 零全局污染：

    • Windows 启动器：仅更新项目目录下的 .mcp.json，不篡改本机全局 Codex 配置。

    • Linux 刷新脚本：默认不修改 ~/.codex/config.toml，仅在显式追加 --sync-codex 时作为遗留兼容同步。

🌐 免费 ngrok 配置指南（手把手白嫖）

推荐使用免费的 ngrok 提供稳定的公网隧道支持（完全免费）：

  1. 注册账号：访问 ngrok 官网 (ngrok.com) 免费注册一个账号。

  2. 获取 Authtoken：

  3. （强烈推荐）领取 1 个免费静态域名：

    • 在左侧菜单点击 Cloud Edge -> Domains。

    • 点击 Claim a domain，免费领取一个专属静态域名（如 your-name.ngrok-free.app）。

    • 好处：固定域名后，每次重启服务都不需要在 ChatGPT 网页端重新更新 URL！

  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 的 Owner 密码（保存在 ~/.devspace/auth.json 中）完成授权。

  4. 开启新对话，点击工具栏中的连接器图标，即可让 ChatGPT 读取、编写、运行你的本地代码！

🛠️ 诊断工具箱与命令行命令

本仓库内置了一套完善的诊断与运维命令：

# 🔍 综合诊断与能力探针
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 用 publicBaseUrl 推导 OAuth issuer，再拼接 /mcp 作为 MCP 端点。

  • 解决方案：确保 publicBaseUrl 为纯域名根（无后缀），仅在客户端填写的连接 URL 中携带 /mcp。本项目脚本已做自动化修正。

  • 报错表现：非交互环境下找不到命令，或 npm 软链无执行权限。

  • 解决方案：本项目启动脚本会自动补全 PATH 环境变量，并内置 chmod +x 自愈逻辑。如需手动修复可执行：

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

  • 原因剖析：传统的 pkill -f 模式会匹配到当前脚本自身的命令行参数导致误伤。

  • 解决方案：本项目改为记录 PID 并结合 Linux /proc 启动标识/Windows 进程归属链进行精准终止。

  • 原因剖析：setsid 无法直接调用 Shell 内建命令 eval。

  • 解决方案：统一封装为 setsid bash -c "$CMD" 调用。

  • 原因剖析：上游 DevSpace 默认会在 open_workspace 等工具调用时挂载完整 MCP App，导致频繁创建 iframe；且原组件依赖从 ngrok 加载资源，会被免费隧道的安全拦截页阻断。

  • 解决方案：本项目在内存中对模块进行兼容性适配：

    1. 仅对最终的 show_changes 挂载 UI 资源；

    2. 使用完全自包含且版本化的内联 Diff 组件（ui://devspace/diff-card-inline-v3.html）；

    3. 修改后请在 ChatGPT Connector 设置中点击 Refresh 并开启新对话测试。

  • 说明：如果不配置固定域名，免费隧道每次重启域名可能变更。建议在 ngrok Dashboard 免费领取 1 个静态域名，即可一劳永逸无需重复更新 ChatGPT 端点。

  • 休眠恢复：Windows 唤醒或网络恢复后，受管进程会监测公网健康并自动重建 ngrok 会话。透明恢复依赖 NGROK_DOMAIN 固定域名；随机域名变化后 ChatGPT 保存的连接器地址无法自动更新。

🛡️ 安全规范与免责声明

  1. 凭据隔离：严禁提交 .env.local、~/.devspace/auth.json、运行日志或真实 .mcp.json 到任何公共代码库。

  2. 风险可控：公网隧道具备可访问性，请仅在需要时开启；如怀疑凭据泄露，请立即运行 node oauth-admin.mjs revoke-all --yes 并轮换 Token。

  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），您可以在合法合规的前提下自由学习、修改与二次分发。

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivitySlowing
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers