MCP 连线诊断与故障复原

返回 Codex 教学总目录

目标与准备

本段提到的教学与资源: MCP 入门

步骤 1：先查设定，别急著改逾时

codex --version
codex mcp get codexLearningDocs
codex mcp list

确认输出中的名称、enabled、传输方式与 URL，并记下本机还是远端主机、CLI 或桌面入口，以及最后一次重新启动的时间。若 get 找不到名称，回到实际 config.toml；拼字、使用者层与专案层，以及自订 CODEX_HOME 都要逐项核对。桌面、CLI、IDE 只有在同一 Codex 主机下才共用设定，Windows 原生与 WSL 的家目录也不能当成同一个位置。

设定档解析失败时，先处理行号附近的引号、重复表格或错误类型，再谈网路。用设定篇的方法保存自己的修改前副本，只修改练习区段；不要把整份设定贴上公开求助。若档案能解析但名称仍不见，检查可信任专案的载入与当前工作目录，并确认编辑器保存的是实际档案，不是另一份备份。

公开文件服务没有认证要求时，该栏填「不需要」，不是漏做登入。

步骤 2：重现工具被停用的情况

先用前篇的唯读问题取得一次正常结果并保存原设定。既有练习区段已有 enabled 时把原值改为 false；没有才新增一次 enabled = false，不能重复键或表格。桌面按 MCP 设定中的 Restart，IDE 重新启动扩充套件，CLI 结束后开新工作阶段。不要只在旧对话重新问一句，因为它仍可能引用已读过的内容。这个练习刻意让伺服器不可用，不代表远端官方服务真的坏了。

[mcp_servers.codexLearningDocs]
url = "https://developers.openai.com/mcp"
enabled = false

/mcp

/mcp 可在桌面版、CLI、IDE 的 Codex 输入框使用，不是终端机命令。重新启动后，在新任务／工作阶段同时用 /mcp、MCP servers 设定与实际工具活动确认停用。记录「客户端未提供工具」即可；跨入口测试要另记主机与设定位置。

预期新工作阶段不再提供这个已停用伺服器的工具。此时即使 get 仍列出它，也符合预期：设定存在与工具可用是不同状态。把 enabled 改回 true 或移除这次加入的 false，重新启动后重做查询并核对官方原文。保存「正常 → 停用 → 恢复」三个结果，不能只保存最后成功画面，否则看不出故障演练是否真的生效。

步骤 3：区分 STDIO 启动与 HTTP 连线

如果你使用其他 STDIO 伺服器，先看 command、args 与 cwd。Windows 用 Get-Command 查启动程式，macOS、Linux 用 command -v；这只证明目前终端机找得到程式，不保证从桌面启动的程序 PATH 完全一样。相对路径会受工作目录影响，档案不存在先修正路径；需要 Node.js 的伺服器则核对 Node 版本。不要为档名打错直接拉长启动逾时。

Get-Command node
node --version

command -v node
node --version

STDIO 伺服器把标准输入输出当协定通道，额外印出欢迎文字或除错资料可能干扰连线。若你维护该伺服器，依其官方实作把一般纪录写到 stderr；若只是使用者，记录启动错误交给提供者，不要随意改第三方套件内容。手动启动后等待输入而没有文字，不必然是当机；看到程序活著也不等于 MCP 已成功初始化。

HTTP 则先核对完整协定、主机、路径，例如本篇必须是官方 /mcp 端点。浏览器能开网站首页，只能证明部分网路可达，不能证明 MCP 请求、代理设定与验证都成功。TLS 错误应检查系统时间、公司代理与凭证信任设定；先向环境维护者确认，不把关闭凭证验证当成教学预设。暂时连不上时保留时间与遮蔽后错误再重试。

步骤 4：认证、工具筛选与逾时

需要 OAuth 的服务可以在客户端按 Authenticate，或先查 codex mcp login --help 再以自己的伺服器名称登入。要用哪个帐号、哪些权限，以及回呼网址都依提供者规格；若需要预先注册 client ID，就注册 Codex 显示的完整回呼网址，不能猜固定埠或把 localhost 和 127.0.0.1 任意互换。公开 Docs MCP 不用这项登入练习。

认证已完成但看不到某个工具时，查看 enabled_tools、disabled_tools 与插件本身的工具政策。允许清单不会创造伺服器没有提供的能力；同名工具同时列在两份清单时，停用清单在允许清单之后套用。先用目前工具目录取得真正名称，不要猜成 search 或 read。插件提供的伺服器另有插件层设定，使用者设定不负责改写它的启动命令，详见 Plugins 排除问题。

启动逾时与工具执行逾时是不同阶段：startup_timeout_sec 只处理初始化等待，tool_timeout_sec 处理单次工具。先确认程式、网址、认证都对，再用较小的唯读请求判断是否只是工作太大；只有确定是合理等待不足才调整那个伺服器的值并重测。optional startup grace 与 required 也会影响启动时的行为，新手不必把所有伺服器改成 required；无法启动的重要服务应保留错误并停止依赖它的工作。

收尾：可交接的故障纪录

# MCP recovery record
Surface / OS / client version:
Host and effective config location (redacted):
Server name / transport:
Failure layer:
Original error (without secrets):
Single change:
New-session tool visibility:
Read-only request and verified source:
Normal / disabled / restored results:
Unrelated settings preserved:
Remaining limitation and next action:

如果练习改坏设定，先恢复本次练习区段，重新读取确认；不要在其他任务同时写设定时整档还原。结束后按前篇移除自己新增的 codexLearningDocs 即可。OAuth 服务的 logout 用于清除该服务的已存认证，remove 用于移除设定；是否还有外部授权，要到提供者的帐号页确认。两者都不能撤销已经写进外部系统的资料，涉及写入要依原服务自己的复原流程处理。

完成标准是能解释哪一层失败、提供一次可重现的停用与恢复，以及新的唯读工具证据；只看到程序、设定档或正确答案都不够。尚未取得连线时保留「未完成工具验证」，不用把未测环境填成正常。本篇产品流程依官方文件查证，本机设定与直接 MCP 协定验证另存纪录；macOS、Linux、IDE、OAuth 与实体手机未因这些测试而自动取得实测标记。下一步进入 Worktree 隔离。

返回 Codex 教学总目录

阅读完整文字说明

Three numbered stages: identify the starting point, perform the exercise, and verify the result. Original illustration, not a product screenshot.

• AI 工具
• 教程
• Codex