CodeGym /课程 /ChatGPT Apps /在 ChatGPT 中使用 Dev M...

在 ChatGPT 中使用 Dev Mode：连接本地应用

ChatGPT Apps

第 2 级 , 课程 3

可用

1. 从实用角度理解 Developer Mode

你已经对 Dev Mode 有一些了解，但现在更重要的是基于真实实践拼出完整图景。

在 ChatGPT 中，Developer Mode 是一个特殊模式，平台允许你直接连接自己的应用，无需发布到 Store。你对 ChatGPT 说：“这是我的 MCP 服务器的 URL”，然后 ChatGPT 会把它当作带 UI 的外部工具——可以调用其工具、加载你的小组件（widget），并把这一切呈现在常规聊天中。

回到架构层面，在 Dev Mode 下 ChatGPT 充当 MCP 客户端，而你的 Next.js 模板是 MCP 服务器。ChatGPT 会与 /mcp 建立连接，询问“你会什么？”（tools 和 resources 列表），之后在对话过程中调用这些工具，并在 iframe 中显示你的小组件。

务必区分 Dev Mode 与 Store：

Dev Mode 是你个人的小“车库”：可以随意折腾、做实验、每五分钟就改一次工具的 schema，而不必顾虑用户。
Store 是展示橱窗：那里是已经稳定的版本，经过审核并且配好政策、描述等。我们会在课程末尾去那里；现在还在车库里玩。

截至 2025 年底，带 Apps SDK 的 Dev Mode 在所有 ChatGPT 套餐上可用，但在企业账户中有时需要管理员在工作空间级别启用。如果你在设置里看不到 Developer Mode 开关，这是首要检查项。

2. 开始本讲前你应具备的内容

在点击 ChatGPT 界面里的任何东西之前，先确保本地部分已经准备好。

首先是 Next.js 的 dev 服务器。在项目根目录你已经运行过：

npm run dev

默认情况下，Next.js 16 监听端口 3000，因此你的 UI 可以通过 http://localhost:3000 访问。

其次是 MCP 路由。在 CodeGym Labs 模板中，MCP 服务器作为 route‑handler 实现在 app/mcp/route.ts。工具和资源在这里注册；当你在 Dev Mode 中连接应用时，ChatGPT 的首批请求也会打到这里。

从架构角度，现在大致是这样：

你的浏览器 ──> http://localhost:3000 (Next.js dev, UI)
                           │
                           └── /mcp (Next.js 内的 MCP 服务器)

目前与 ChatGPT 之间还没有任何连接——它在云端运行，无法看到你的 localhost。关于隧道的详细设置是下一讲的主题。这里为简单起见，假设你已经有一个指向 /mcp 的公共 HTTPS URL（例如通过 ngrok 或 Cloudflare Tunnel，按模板 README 配好）。

如果你尚未搭起隧道——也没关系。现在至少可以先过一遍 Dev Mode 的整个步骤链，看看当你得到 HTTPS URL 后需要做什么。

如果你已经有指向 /mcp 的 HTTPS URL，那么接下来可以跟着手把手操作。
如果暂时没有——就把本讲当作“界面导览”来读：先理解步骤链，等下一讲配置好隧道后再真正跑起来。

3. 在界面中启用 ChatGPT 的 Developer Mode

第一步是让 ChatGPT 显示出需要的设置。请按以下步骤操作：

先用将用于开发的账号登录 ChatGPT 的网页端。点击左下角（或右上角——UI 在不断演进）的个人头像，选择 Settings（设置）。

在设置中找到与应用相关的分区：通常叫做 Apps & Connectors 或 Connected apps。打开该分区。在页面底部（或 Advanced / 高级选项卡）会出现一个 Developer Mode 开关。你需要把它打开。

启用 Dev Mode 后，ChatGPT 通常会显示一条“已启用开发者模式”的通知。在同一个分区会出现形如 Create、Create connector、New app 的按钮——文案可能略有不同，但意思一样：现在你可以创建自己的连接应用了。

如果在设置里完全看不到 Apps & Connectors 分区，或没有 Developer Mode 开关，请检查：

你是否确实登录了要用于开发的那个 ChatGPT 账号；
在企业账号中，该模式可能需要由工作区管理员启用。

有时只需退出并重新登录即可（开发者模式的经典“重插网线”）。

4. 创建应用/连接器并填写 MCP URL

现在 Dev Mode 已开启，咱们把你的 GiftGenius 注册到 ChatGPT。下面这套流程是“正式做法”。如果 HTTPS URL 还未配置，就当作预演：先看看等有了隧道后我们会做什么。

一切都在你刚才去过的 ChatGPT 设置分区内完成。大致顺序如下。

再次打开 Settings → Apps & Connectors。里面你会看到已连接的应用列表（大概率还是空的）以及 Create / Add connector 按钮。点击它——会打开创建应用的表单。

这个表单通常包含三个关键字段：

名称（Name）。这是人类可读的名称，你和 ChatGPT 都能看到。课程里建议命名为 GiftGenius (dev)，一眼就知道是本地开发版。
描述（Description）。简要说明应用做什么、在何时使用。示例：“根据对方的兴趣推荐礼物创意”。这行文字会影响发现与召回——模型会用它来判断何时在聊天中推荐你的 App。
MCP 服务器的 URL（有时标为 Connector URL、MCP endpoint、App URL 等）。这是最重要的字段：在此粘贴指向你应用的 /mcp 的公共 HTTPS URL。

例如：

https://my-giftgenius-dev.ngrok.app/mcp

或

https://giftgenius-dev.trycloudflare.com/mcp

该字段的要点：

必须是 https://，否则 ChatGPT 会拒绝连接；
末尾必须带上 /mcp，因为 MCP 服务器就在模板的该路径；官方 Apps SDK 文档也是这样约定的。

关于这个 URL 从何而来，我们会在下一讲详细讲（隧道、Cloudflare、ngrok）。现在要理解的核心是：你的本地 http://localhost:3000/mcp 需要“变成”一个公共的 https://…/mcp，而你要把这个公共地址粘贴到表单里。

填完字段后点击 Create / 保存。此时 ChatGPT 会与服务器“握手”：向该 URL 发送 HTTP 请求，期待收到能力清单（tools/resources 列表与元数据），并验证服务器是否按 MCP 协议响应。如果一切正常，连接器会出现在列表中，你会看到 ChatGPT 发现了哪些工具。下一节我们会拆解握手具体做了什么，以及如何在日志里看到。

如果你还没配置隧道而是填了虚假的 URL，ChatGPT 会如实提示无法连通服务器。这同样是有用的经验：你能立刻看到错误展示在何处以及如何展示。

5. 幕后发生了什么：通俗解释 MCP 握手

从外面看，这像是普通的“按 URL 添加应用”的表单。内部稍微复杂一些，现在弄明白它会对后续调试有很大帮助。

你已经看到，创建连接器时 ChatGPT 会访问你的 /mcp 并期待一个能力清单。现在把这段对话展开一点——这对于调试非常有用。

点击 Create 后，ChatGPT 会做几步操作。

首先，它以 MCP 客户端的身份访问所填的带 /mcp 的 URL。按照 MCP 协议，它期望这个 HTTP endpoint 上有一个服务器，具备基础能力：列出工具（list tools）、提供资源（小组件）、处理工具调用。

服务器随即返回一个 JSON 结构，包含如下描述：

服务器名称与版本；
工具列表：name、title、description、inputSchema 等；
资源列表：从哪里获取你的小组件 HTML、MIME 类型、如何渲染等。

在 CodeGym 的 Next.js 模板中，这些都已经在 app/mcp/route.ts 里实现：通过 SDK 调用类似 server.registerTool(...) 和 server.registerResource(...)。

如果你想“亲眼看到”这个握手过程，可以在 app/mcp/route.ts 里加一个简单的日志。这更像是开发者的调试技巧，可以先跳过，等想深入时再回来：

// app/mcp/route.ts
import { NextRequest, NextResponse } from "next/server";
// 引入你已有的 server / buildManifest

export async function GET(req: NextRequest) {
  console.log("[MCP] Handshake from ChatGPT:", req.headers.get("user-agent"));
  const manifest = buildManifestSomehow(); // 这在模板里已经有了
  return NextResponse.json(manifest);
}

这个函数略显抽象（模板结构可能不同），但核心很简单：app/mcp/route.ts 是一个普通的 Next.js route‑handler，你可以记录入站请求。成功连接 Dev Mode 后，你会在运行 npm run dev 的终端里看到这条日志。

从协议角度，可以画成一张小时序图：

sequenceDiagram
    participant ChatGPT
    participant Tunnel as HTTPS URL (/mcp)
    participant NextDev as Next.js dev + MCP

    ChatGPT->>Tunnel: HTTP(S) 请求到 https://.../mcp
    Tunnel->>NextDev: 代理到 http://localhost:3000/mcp
    NextDev-->>Tunnel: 返回包含工具和资源的 JSON
    Tunnel-->>ChatGPT: 转发响应
    ChatGPT->>ChatGPT: 缓存 tools/resources 列表

你在 Dev Mode 表单里输入的“一个 URL”，实际上触发了一次完整的协议对话。

6. ChatGPT 在连接后如何“看见”你的应用

假设握手顺利完成。接下来会怎样？

首先，在 Apps & Connectors 设置里，你的 GiftGenius (dev) 会出现在已连接应用列表中。卡片内会显示名称、描述和发现的工具列表。通常这里还会有 Refresh、Delete 等按钮。等你修改工具 schema 时，Refresh 会派上用场。

其次，该应用会在聊天中可用。打开一个新聊天，点击输入框旁的“+”。那里会有 “More”、“Apps”、“Tools” 等菜单（取决于当时的 UI 版本）。你的 GiftGenius (dev) 应该会出现在列表里，你可以为本次对话显式选择它。

选择之后，应用会“连接”到此聊天。对你而言，大致是这样：

你用自然语言发起请求，例如：“给一位太空迷选个预算 50$ 的礼物”；
ChatGPT 会根据描述与对话历史判断可否使用 GiftGenius，并调用你的某个 MCP 工具；
调用结果可能包含 HTML 小组件；它会以卡片/面板的形式直接渲染在聊天里。

在 Dev Mode 下，你通常会先通过菜单选择或按名称显式调用应用。但要理解：在生产中，ChatGPT 也可能根据描述与工具元数据“主动推荐”你的 App。

为了直观理解，再看一张小表格：

你所在的位置	你看到的内容	这意味着什么
Settings	GiftGenius (dev) 出现在应用列表	已创建连接器，MCP 正常
Chat → “+”	GiftGenius (dev) 出现在 Apps/Tools 列表	可以连接到当前聊天
对话	文本 + GiftGenius 的小组件/卡片	通过 MCP 进行了工具调用

7. 开发循环：改代码 → 在 ChatGPT 中看到效果

把 App 连上只是完成了一半；另一半是理解在日常开发中如何与 Dev Mode 协作。

变更大致分两类：UI（小组件）变更与 MCP 逻辑/工具变更。

如果你只改 UI，例如在 app/page.tsx 里调整标题或样式，这对 Next.js 来说就是常规前端。dev 服务器会热重载模块，你在浏览器里能看到 hot reload。在 ChatGPT 中，你的 UI 是在 iframe 中打开的，但表现类似：当下次调用会渲染该小组件的工具时，ChatGPT 会加载更新后的 HTML。有时 HMR 会直接作用到 iframe，有时只需要在聊天里重新触发工具调用即可。缓存

动手试一下，稍微改动小组件。假设在 app/page.tsx 里有类似：

export default function GiftGeniusWidget() {
  return (
    <main style={{ padding: 16 }}>
      <h1>GiftGenius</h1>
      <p>这里将展示礼物推荐。</p>
    </main>
  );
}

把标题和文本改成：

export default function GiftGeniusWidget() {
  return (
    <main style={{ padding: 16 }}>
      <h1>GiftGenius (dev)</h1>
      <p>此版本运行在 Dev Mode。不要用于生产环境。</p>
    </main>
  );
}

保存文件，回到连接了 GiftGenius 的聊天，再次调用应用（例如用同样的礼物请求）。你应该能在小组件内看到更新后的标题——这说明 Next.js → 隧道 → ChatGPT 的链路工作正常。

如果你修改了MCP 部分——新增工具、调整 inputSchema、修改工具名称——就会触发 ChatGPT 的缓存。首次连接 Dev Mode 时，ChatGPT 会记住工具列表，并不总是自动拾取变更。这时需要回到 Apps & Connectors，选择你的 GiftGenius (dev)，点击类似 Refresh schema / Refresh 的按钮。之后 ChatGPT 会重新请求你的 /mcp 并更新工具列表。

这看似细节，但很容易“踩坑”：你已经改了工具代码，ChatGPT 却迟迟看不到新的参数。

8. 迷你实操：在 Dev Mode 中跑通第一个 GiftGenius 场景

把所有内容串起来做个实践。这里假设你已经有一个可用的 /mcp 的 HTTPS URL（通过隧道或部署）。如果还没有——先阅读步骤，下一讲配好真实 URL 再跟做。

确认 npm run dev 已启动且日志无错误。如果模板有日志，能在终端里看到类似 “MCP server running at http://localhost:3000/mcp” 的提示会更安心。
打开 ChatGPT，通过 Settings → Apps & Connectors → Advanced settings 启用 Developer Mode。
创建新的连接器 GiftGenius (dev)，填一个简短描述（“Helper for choosing gifts”），URL 形如 https://<your-domain>/mcp。
确认 ChatGPT 能成功连接：在应用列表里你会看到新的条目。如果连接失败——请查看 dev 服务器与隧道的日志，这本身就很有帮助。
打开一个新聊天，点击“+”，选择你的 GiftGenius (dev)，然后发起请求：“给一位喜欢太空与咖啡的开发者推荐礼物，预算 40$。”
看看当前模板会做什么：基础形态可能只是展示一张简单的卡片/小组件。它还不是“智能礼物推荐”，但能在聊天里显示来自你代码的内容——这已经是巨大的进步。

作为额外练习，你可以在 MCP 服务器里加一个专用于 Dev Mode 的测试工具。示例（现在不一定要实现，先看看思路）：

// 在 app/mcp/route.ts 内，与其他 tools 并列
server.registerTool(
  "ping_dev",
  {
    title: "Ping GiftGenius dev",
    description: "检查 Dev 服务器是否存活。",
    inputSchema: { type: "object", properties: {} },
  },
  async () => ({
    content: [{ type: "text", text: "GiftGenius dev is alive ✅" }],
    structuredContent: {},
  })
);

我们会在“工具”模块里详细讲解 server.registerTool。现在先记住：通过 MCP 你描述“你的 App 会什么”，而 Dev Mode 则是把这个 URL 交给 ChatGPT 的方式。

9. 去哪里看错误，以及如何判断“是我这边坏了”还是“ChatGPT 那边坏了”

没人愿意花半小时在“系统的另一半”里找 bug，所以从一开始就要养成在正确的地方查问题的习惯。

如果在创建连接器时出错。当 ChatGPT 提示无法连接你的 App，首先查看你自己的 dev 服务器和隧道日志。如果运行 npm run dev 的终端里完全看不到打到 /mcp 的入站请求——问题在 ChatGPT → 隧道这条路径上。如果有请求，但服务器返回 500 或在控制台报错崩溃——问题在你的 MCP 代码。

如果连接器已创建，但在聊天里出错。当连接器已经创建，但聊天里间或出现 “App unavailable / App broken” 的横幅，几乎总意味着：

dev 服务器挂了（Next.js 不再监听端口 3000）；
隧道关闭或 URL 变了；
MCP endpoint 返回错误、超时或响应过慢。

关于 UI/小组件的单独说明。遇到 UI 问题（小组件不渲染、空白屏、样式异常），也请查看浏览器的 DevTools。小组件是在 iframe 中加载的，该 iframe 的控制台会显示 JavaScript/React 的错误——与普通 Web 应用一致。

随着经验增长，你会逐渐能“闻出”是“隧道的味道”还是“Next.js 的味道”，仅凭错误形态就能判断。但现在只要记住：你有三处潜在故障点——你的代码、隧道和 ChatGPT，而问题出在 ChatGPT 的概率通常最低。

Insight

如果你读到这里还没有付费的隧道服务，那就现在买一个吧。反正你在接下来几天内也会用到它。不如现在就下决心，给自己省点心。

10. 使用 Dev Mode 的常见错误

错误 №1：忘记开启 Developer Mode，找 Create 按钮找了半小时。
有的开发者一上来就进 ChatGPT，点 Apps & Connectors 设置，但什么都看不到。若没开启 Developer Mode，创建连接器的按钮可能根本不会出现。总是先检查在 Advanced settings 里是否开启了 Dev Mode，特别是在新账号或换了浏览器的情况下。

错误 №2：填写了没有 /mcp 的 URL，或根本不是 MCP endpoint。
经典错误：把 https://myapp-dev.ngrok.app（没有 /mcp）或其他服务/落地页的 URL 填进去了。ChatGPT 会礼貌地按 MCP 协议去请求，却找不到期望的接口，最终报连接失败。Next.js 入门模板明确写着：要连接的 URL 必须指向 /mcp，这也正是你在 Dev Mode 中应填写的地址。

错误 №3：尝试直接使用 http://localhost:3000/mcp。
直觉上你可能想把 dev 服务器日志里出现的 http://localhost:3000/mcp 填进去。但 ChatGPT 跑在云端，不在你的笔记本上，它无法访问你的 localhost。此外 ChatGPT 还要求 HTTPS。所以没有隧道或远程部署是不可能成功的。这不是 ChatGPT 的 bug，而是正常的网络隔离。

错误 №4：修改了 MCP schema 后忘了点 Refresh。
完成首次握手后，ChatGPT 会缓存工具和元数据列表，从而避免每次都打你的服务器。如果你新增了 tool 或修改了它的 inputSchema，而 ChatGPT 仍按老样子行事，几乎肯定需要在 Apps & Connectors 里对连接器执行 Refresh。不刷新，模型就不知道工具发生了变化。

错误 №5：dev 服务器都没启动就调试 Dev Mode。
听起来显而易见，但很常见：有人远程配置 Dev Mode 和隧道，却忘了本地终端里的 npm run dev 早就停了，或者项目因语法错误无法编译。只要本地 dev 服务器趴着，调 Dev Mode 就毫无意义。总是先确保 http://localhost:3000 在你的浏览器里能正常访问，然后再连接 ChatGPT。

错误 №6：以为 Dev Mode 是“另一种什么都懂的模型”。
有时会误以为启用 Dev Mode 后，模型就“全都知道”了。实际上，Dev Mode 并不会改变模型本身，它只是让模型能访问你的 MCP 服务器与工具。如果工具定义含糊、App 描述不清，或服务器逻辑古怪，模型也会像任何开发者在面对文档糟糕的 API 时一样困惑。好的元数据与工具设计是后续模块的话题，但这点现在就要牢记。

错误 №7：把 Dev Mode 当生产用。
有时会有诱惑：“既然 Dev Mode 下跑得不错，就把链接给用户，让他们用这个 URL 连接 App 吧。”问题是 Dev Mode 并非为大规模使用而生：隧道不稳定、配置容易损坏，ChatGPT 也可能在无兼容保证的情况下调整 Dev Mode 的行为。面向真实用户请走 Store 与生产部署。Dev Mode 仅是你的实验室环境。

上一课上一课

下一课下一课

TO VIEW ALL COMMENTS OR TO MAKE A COMMENT,
GO TO FULL VERSION