通过 Secure MCP Tunnel 让 ChatGPT 网页端操控本地文件（完整配置指南）

从本地 MCP、OpenAI Tunnel、runtime key、tunnel-client 到 ChatGPT Web 自定义 App，完整配置网页端读取、修改本地文件并按需执行命令的 Agent-like 工作流。

#howto #growing #ai #openai #mcp #chatgpt #cli #windows

[!abstract] 一句话 ChatGPT 网页端不能直接访问你电脑的 localhost。正确做法是：本机 MCP Server 提供“手脚” → tunnel-client 建立只出站的 Secure MCP Tunnel → ChatGPT 自定义 App 看到这些工具 → Skill / Agent 指令规定怎么像 Coding Agent 一样循环工作。

[!warning] 名词纠正常见口误里的 “NCP” 指的是 MCP（Model Context Protocol）；“Terminal” 在这条链路里通常实际指 Tunnel（隧道）。Terminal 是终端，Tunnel 才是把本地 MCP 接到 ChatGPT 的那一层。

[!warning] 不记录真实凭据本文所有 ID 与 key 都是占位符。真实 key 只进入当前进程环境变量、Git 忽略的本地环境文件或系统凭据存储，不进入 Git、知识库、截图和聊天记录。

[!info] related notes

本地知识库专用 MCP: 构建 Thought Forest 本地知识库 MCP Server

Tunnel 对象: OpenAI Secure MCP Tunnel

ChatGPT App / Skill / Agent: 配置 ChatGPT App、Skill 与 Workspace Agent

Modern Runtime 架构: Modern ChatGPT Local MCP Agent Runtime 架构

可靠性实施基线: MCP Agent Runtime 可靠性基线

长任务: MCP 持久化 Job Manager

filesystem + shell 代理实现: 用代理模式给官方 MCP Server 注入自定义工具

排障: ChatGPT 本地知识库维护链路故障排查

通过 Secure MCP Tunnel 让 ChatGPT 网页端操控本地文件

0.1 2026-10-01：Modern Local MCP 运行基线

[!important] 这篇笔记负责“怎么接通”；运行时为什么要这样设计，统一看 Modern ChatGPT Local MCP Agent Runtime 架构。

当前推荐不要再把 Local MCP 理解成“Tunnel + 一个可以无限等待的 run_command”。Broad coding agent 应使用：

短同步 RPC：default 20s / hard max 30s
长任务：persistent Job API
control-plane inflight：1
MCP short-call concurrency：4
filesystem / logs：bounded + paginated
stdio：initialized notification lifecycle
observability：tool_start / tool_end / tool_fail

这些数字是当前 GCP / WSL / Oracle2 的经验基线，不是 MCP 协议规定。纯知识查询 MCP 可以采用不同并发策略。

关键规则：构建、全量测试、依赖安装、Coding Agent、未知耗时脚本不要直接持有长同步 RPC；改用 Job Manager。

完整实施检查见 mcp-agent-reliability-baseline。

0. 最终要搭成什么

最小可用链路：

ChatGPT Web
   ↓
自定义 MCP App
   ↓
OpenAI-hosted Tunnel endpoint
   ↓
HTTPS 出站连接
   ↓
tunnel-client（你的电脑）
   ↓
本地 MCP Server
   ↓
本地文件 / 项目

如果想进一步像 Coding Agent：

ChatGPT Web
   ↓ 规划
read/search
   ↓
edit/write
   ↓
run_command
   ↓
test / lint / git diff
   ↓
读取错误
   ↓
继续修改

这里四层职责必须分清：

层	人话
MCP Server	真正拥有本地权限的“手脚”，定义能读什么、写什么、能不能跑命令
Secure MCP Tunnel	只负责把 ChatGPT 的工具请求安全送到本机，再把结果送回去
ChatGPT App	ChatGPT 侧登记这套工具，让聊天能选择和调用它
Skill / Agent 指令	规定“先读什么、怎么修改、怎么验证”的工作流程，是“大脑 SOP”

Tunnel 本身没有文件权限；权限来自 MCP Server。

1. 先决定要开放多大权限

方案 A：只操作文件

适合文档、知识库、配置文件：

list / search
read
write
edit / move

推荐限制在明确目录，例如：

D:\home\thought-forest
D:\home\MemoFlow

而不是整个 C:\ 或 D:\。

方案 B：文件 + shell，真正接近 Coding Agent

除了文件工具，再提供：

run_command(command, cwd, timeout)       # 仅短同步命令
job_start / status / output / cancel     # 长任务

这样 ChatGPT 才能同时获得“快速同步控制”和“可靠长任务执行”：

git status、git diff、小范围 grep 走同步命令；
npm / pnpm / pytest / go test 若可能超过同步预算，走 Job；
构建、依赖安装和 Coding Agent 默认走 Job；
Job 日志通过 offset/limit 分段读取，不把大输出一次塞回 ChatGPT。

[!danger] shell / Job 是强权限一旦暴露任意 shell，filesystem 的路径白名单不再是真正安全边界，因为 shell 本身可以读取其他路径。只在可信机器、可信工作区和明确的项目作用域下使用，并把危险写操作设为需要确认。同步 shell 还必须有 hard timeout；超过预算的命令应快速拒绝并要求改用 Job，而不是把 timeout 无限放大。

Thought Forest 知识库本身更适合继续使用语义化、受限的 12 个知识库工具，而不是任意 shell。

2. 准备本地 MCP Server

如果已经有可用的 MCP（例如 Thought Forest KB、agent-v2、combined-mcp），直接复用它，不要为了 Tunnel 重写一套。

如果只是快速搭一个文件 MCP，可使用官方/社区常用 filesystem server，并把根目录限制在目标项目。Windows 更推荐包一层启动脚本，避免 cwd、PATH 和引号问题。

示意：

@echo off
cd /d D:\home
npx -y @modelcontextprotocol/server-filesystem "D:\home"

保存为例如：

D:\tools\local-agent-mcp\run.cmd

本地先验证它能独立启动。stdio MCP 启动后“卡住等待输入”是正常状态，因为它在等待 JSON-RPC。

如果要加入 run_command，优先复用现有代理型实现，详见 MCP 代理桥；不要为了 shell 重写官方 filesystem 的整套路径逻辑。

3. OpenAI Platform：创建 Tunnel

官方入口：

Tunnel 管理：https://platform.openai.com/settings/organization/tunnels
Organization Roles：https://platform.openai.com/settings/organization/people/roles
Organization Groups：https://platform.openai.com/settings/organization/people/groups

创建或编辑 Tunnel 的操作者需要：

Tunnels Read + Manage

运行 tunnel-client、以及在 ChatGPT 创建 App 时选择 Tunnel，需要：

Tunnels Read + Use

创建 Tunnel 时最重要的是：

记录准确的 tunnel_id；
关联拥有它的 Platform Organization；
关联目标 ChatGPT Workspace；
如果多个工作区/组织都要使用，再显式增加 association。

典型 ID：

tunnel_0123456789abcdef0123456789abcdef

[!warning] Platform 可见 ≠ ChatGPT 可见 Tunnel 只关联 Platform Organization，而没有关联目标 ChatGPT Workspace 时，它可能在 Platform 中存在，但 ChatGPT 的 Tunnel picker 里完全看不到。

4. 创建 runtime API key

入口：

https://platform.openai.com/settings/organization/api-keys

这是给长期运行的 tunnel-client 使用的 runtime key，环境变量名推荐：

CONTROL_PLANE_API_KEY

创建时：

选择 Restricted；
只授予：
- Tunnels Read
- Tunnels Use
不要给 All；
不要用 Admin Key 代替长期 runtime key。

另外一个完全不同的页面：

https://platform.openai.com/settings/organization/admin-keys

OPENAI_ADMIN_KEY 只用于 CLI 创建 / 修改 / 删除 Tunnel 等管理动作。普通机器上的 tunnel daemon 不需要它。

记住三样东西

值	从哪里拿	用来干什么
`tunnel_id`	Platform Tunnels	标识是哪条 Tunnel
`CONTROL_PLANE_API_KEY`	Runtime API keys	让 `tunnel-client doctor/run` 登录控制面
`OPENAI_ADMIN_KEY`	Admin API keys	仅做 Tunnel CRUD，通常不需要

5. 下载 tunnel-client

优先入口：

Platform Tunnels 页中的官方 Download；
最新公开 Release：https://github.com/openai/tunnel-client/releases/latest

放到例如：

D:\tools\tunnel-client\tunnel-client.exe

PowerShell 验证：

D:\tools\tunnel-client\tunnel-client.exe --version
D:\tools\tunnel-client\tunnel-client.exe help quickstart

如果已经加入 PATH：

tunnel-client --version
tunnel-client help quickstart

6. 在本机配置 Tunnel profile

6.1 先临时放入 runtime key

PowerShell 当前窗口：

$env:CONTROL_PLANE_API_KEY = "sk-REDACTED"
$tunnelId = "tunnel_0123456789abcdef0123456789abcdef"

这只在当前 PowerShell 进程生效，适合第一次测试。

长期运行时，把 key 放到：

Git 忽略的本机 .env；
Windows Credential Manager / 其他 secret store；
或由启动脚本从安全位置注入。

不要把 key 写进提交到 Git 的 YAML。

6.2 为 stdio MCP 创建 profile

Windows 推荐让 tunnel-client 调一个简单 wrapper：

tunnel-client init `
  --sample sample_mcp_stdio_local `
  --profile local-agent `
  --tunnel-id $tunnelId `
  --mcp-command 'cmd /c "D:\tools\local-agent-mcp\run.cmd"'

如果 MCP 本身是 HTTP / Streamable HTTP：

tunnel-client init `
  --sample sample_mcp_http_local `
  --profile local-agent `
  --tunnel-id $tunnelId `
  --mcp-server-url "http://127.0.x.x:8787/mcp"

核心思想只有三个配置：

runtime key
+ tunnel_id
+ 本地 MCP 地址/启动命令

7. 先 doctor，再 run

不要一上来就常驻。

tunnel-client doctor --profile local-agent --explain

Doctor 应确认：

runtime key 有效；
tunnel_id 可见；
Read + Use 权限正确；
profile 能解析；
本地 MCP 能启动/连接；
工具发现成功；
网络可连接 OpenAI 控制面。

通过后：

tunnel-client run --profile local-agent

保持这个进程运行。

Tunnel 只需要本机向外访问：

api.openai.com:443

默认不需要开放入站端口，也不需要把本地 MCP 公网暴露出去。

运行时可检查：

/healthz
/readyz
/metrics
本地 /ui 管理界面

具体 localhost 端口以 tunnel-client run 输出或 profile 为准。

8. ChatGPT Web：打开 Developer Mode

完整 MCP 写/改能力当前主要面向支持该能力的 Business、Enterprise/Edu Workspace。不同套餐和 rollout 的菜单名称可能略有差异。

常见入口：

Workspace Settings
→ Apps
→ Create

或：

Settings
→ Apps
→ Advanced Settings
→ Developer Mode

当前 Connector / App 设置入口也可从：

https://chatgpt.com/#settings/Connectors

进入。

如果看不到 Developer Mode：

Business：通常需要 Admin / Owner；
Enterprise/Edu：管理员可通过 RBAC 给开发者授权，然后用户自己打开 Developer Mode。

Developer Mode 权限和 Platform Tunnel 权限是两件事，缺一不可。

9. 在 ChatGPT 创建自定义 MCP App

当前 UI 可能显示 App / Plugin / Connector 等不同名称，但核心步骤相同：

打开 Apps / Plugins / Connectors；
点击 Create 或 +；
新建 developer-mode custom MCP app；
Connection 选择 Tunnel；
从列表选择正确 Tunnel，或粘贴准确的 tunnel_id；
填写名称和描述；
Authentication 按本地 MCP 实际需要配置；
点击 Scan Tools；
等待工具扫描完成；
检查 read / write / destructive 标注；
点击 Create。

例如：

Name: Local Coding Agent
Description: Read, edit and verify files in my local development workspace through a private MCP tunnel.
Connection: Tunnel
Tunnel: tunnel_...

成功后，Draft App 应出现在 ChatGPT 的 Apps / Enabled Apps 中。

10. 第一次只做最小测试

先测读：

使用 Local Coding Agent，列出允许访问的项目根目录。
不要修改任何文件。

再测写：

在测试目录创建 test-from-chatgpt.txt，
内容为 "hello from ChatGPT"。
不要修改其他文件。

如果有 shell，再测：

在允许的项目目录执行 git status --short，
只返回结果，不做任何修改。

只有这三步都可靠，才开始把它当 Agent 使用。

11. 把“有工具”升级成“像 Agent 一样工作”

自定义 MCP App 只解决“ChatGPT 有手脚”。

真正稳定的 Coding Agent 还需要流程层。推荐固定下面的 Bootstrap：

1. 找到 repo root
2. 读取 AGENTS.md / AGENT.md
3. 查看 git status --short 与当前 branch
4. 搜索当前任务相关文件
5. 先读再改
6. 修改后运行测试 / lint / typecheck
7. 查看 git diff
8. 如果失败，读取错误继续修改
9. 验证通过后再总结

这套流程可以放在：

ChatGPT Workspace Agent 的 Instructions；
ChatGPT Skill；
项目级 AGENTS.md；
或普通聊天的长期工作提示中。

当前完整架构见 Modern ChatGPT Local MCP Agent Runtime 架构；Oracle3 时期的旧远程 Coding Agent Harness 仅保留为历史归档。

[!important] 正式 Agent Mode 与这里不是一回事 ChatGPT 的官方 Agent Mode 当前不会使用 custom apps。这里实现的是：普通 ChatGPT 对话 / Workspace Agent + custom MCP app 形成 agent-like loop。

12. 推荐权限模型

文件 MCP

读工具可按需求自动允许。

以下默认要求确认：

write_file
edit_file
move_file
delete_file

shell MCP

run_command 默认按高风险写工具处理。

至少在行为层禁止未经明确要求的：

git push
git reset --hard
git clean -fd
rm -rf
生产部署
修改 secrets
全盘扫描

如果是团队环境，不建议把个人机器上的任意 shell MCP 直接发布给整个 Workspace。

13. 常见故障

ChatGPT 看不到 Tunnel

按顺序检查：

Tunnel 是否关联目标 ChatGPT Workspace；
当前用户是否有 Tunnels Read + Use；
Developer Mode 是否已开启；
是否在正确的 Platform Organization / ChatGPT Workspace。

`404 Tunnel not found`

不要马上当成 RBAC。

先逐字符核对：

tunnel_id；
Organization；
key 对应 principal；
workspace association。

Thought Forest 实践中真实发生过“Tunnel ID 抄错多个相邻字符”导致 404。

Doctor 通过，但 Scan Tools 失败

检查：

tunnel-client run 是否仍在运行；
MCP server 是否真正启动；
stdout 是否被普通日志污染；
工具 schema 是否符合 MCP / ChatGPT 要求。

MCP 有工具，但 ChatGPT 少一个工具

如果是自定义代理工具，检查工具 schema 是否完整。

另外 ChatGPT App 会保存工具快照。Server 改了之后，可能需要 Refresh / 重新审核；某些 Workspace 场景需要重新创建 App。

能读写文件，但不像 Agent

这是正常的。

Tunnel + App 只提供工具，不会自动产生 Observe → Act → Verify → Iterate。需要 Skill / Workspace Agent / AGENTS.md 把流程固定下来。

能改文件，但不能跑测试

说明 MCP 只有 filesystem，没有 shell。

需要增加受控 run_command，或让 ChatGPT 委托本机已有的 Coding Agent。

14. 开机常驻是否必要

第一次调试不要开机自启，手动运行：

tunnel-client run --profile local-agent

稳定后再考虑：

Windows Task Scheduler；
NSSM / service wrapper；
WSL systemd user service。

原则：

只启动一个相同 profile 的实例；
key 不进入任务参数或明文日志；
有健康检查；
有日志轮转；
能手动停用。

Thought Forest 已有对应 Task Scheduler 实现，可继续复用原脚本。

15. 给本地 Agent 自动配置的提示词

下面这段不是给 ChatGPT Web 使用，而是交给已经能操作本机的 Codex / Claude Code / OpenCode / Hermes / 其他 Agent。它负责把本机部分配置到“只差网页上创建 App”的状态。

你现在要把这台机器配置成可以通过 OpenAI Secure MCP Tunnel 被 ChatGPT Web 调用的本地 MCP 执行主机。

目标：
1. ChatGPT Web 最终能够读取、搜索、创建和编辑我指定项目目录中的文件。
2. 如果本机已经存在安全的 filesystem + shell MCP（例如 agent-v2 / combined-mcp），优先复用，不重复造轮子。
3. 如果不存在，先建立最小可用、目录受限的 filesystem MCP；只有在我明确需要 Coding Agent 能力时才增加 run_command。
4. 使用 OpenAI 官方 tunnel-client，把本地 MCP 通过出站 HTTPS 接入我已有或稍后创建的 Secure MCP Tunnel。
5. 所有修改必须可验证、可回滚，不得泄露任何 API key。

执行原则：
- 先检查 OS、Shell、Node/Python、现有 MCP、tunnel-client、PATH 和目标项目目录。
- 先读取已有 AGENTS.md / README / 项目规范，不覆盖已有配置。
- 不要把 CONTROL_PLANE_API_KEY、OPENAI_ADMIN_KEY 或其他 secret 写入 Git、普通 Markdown、日志或 shell history。
- runtime key 只通过环境变量、Git ignored .env 或系统 secret store 注入。
- MCP 的 filesystem root 只开放我指定的目录，不开放整个磁盘。
- 如果增加 run_command，把它视为高权限工具；默认禁止 destructive shell、git push、生产部署和读取 secrets。
- stdout 如果承载 MCP stdio JSON-RPC，不允许输出普通日志；日志写 stderr。
- 优先用 wrapper script 固定 cwd 和绝对路径，避免 Windows 引号/PATH 漂移。
- 不要创建多个重复 tunnel-client daemon。

OpenAI 官方入口：
- Tunnel: https://platform.openai.com/settings/organization/tunnels
- Runtime API keys: https://platform.openai.com/settings/organization/api-keys
- Roles: https://platform.openai.com/settings/organization/people/roles
- Groups: https://platform.openai.com/settings/organization/people/groups
- tunnel-client latest: https://github.com/openai/tunnel-client/releases/latest
- ChatGPT connector settings: https://chatgpt.com/#settings/Connectors

本机实施步骤：
A. 盘点现状，并明确将复用哪个 MCP server。
B. 本地独立验证 MCP tools/list 和至少一次 read 操作。
C. 安装/确认 tunnel-client，执行 tunnel-client help quickstart。
D. 如果当前环境中已有 CONTROL_PLANE_API_KEY 和 tunnel_id，则直接继续；如果没有，不要伪造，停在这里并准确告诉我需要从哪个网页取得哪一个值。
E. 创建 named profile，优先使用：
   tunnel-client init --sample sample_mcp_stdio_local --profile local-agent --tunnel-id <TUNNEL_ID> --mcp-command "<ABSOLUTE_WRAPPER_COMMAND>"
   HTTP MCP 则改用 --mcp-server-url。
F. 运行：
   tunnel-client doctor --profile local-agent --explain
   修复到 doctor 通过。
G. 运行：
   tunnel-client run --profile local-agent
   验证 healthz / readyz / 本地 /ui 正常，并确认只存在一个 daemon。
H. 输出 ChatGPT Web 剩余人工步骤：
   Developer Mode → Apps/Plugins/Connectors → Create/+ → Connection=Tunnel → 选择 tunnel → Scan Tools → 检查权限 → Create。
I. 给我三个验收提示词：只读测试、写文件测试、run_command 测试（如果 shell 已启用）。

完成后只汇报：
- MCP server 启动方式
- 允许访问的根目录
- tunnel-client 路径和 profile 名
- doctor / ready 状态
- ChatGPT Web 还需要做的步骤
- 你实际修改了哪些文件
- 回滚方法

不要打印任何完整 secret。

16. 最终验收清单

官方资料

OpenAI Secure MCP Tunnel: https://developers.openai.com/api/docs/guides/secure-mcp-tunnels
OpenAI tunnel-client: https://github.com/openai/tunnel-client
Developer mode and MCP apps in ChatGPT: https://help.openai.com/en/articles/12584461-developer-mode-and-mcp-apps-in-chatgpt