一、前言

最近 AI 编程工具圈子里，MCP（Model Context Protocol）服务器可谓是风头正劲。其中，codebase-memory-mcp 凭借“毫秒级索引代码库、158 种语言支持、99% 省 Token”的亮眼表现，吸引了不少开发者尝鲜。我也忍不住在 Windows 上试了一把，结果却踩了一个大坑——安装完这个项目后，Codex 桌面版直接“瘫痪”了，一直卡在“Windows 安装未完成”的提示页面上，无论怎么重装都无效。更诡异的是，删除 codebase-memory-mcp 项目后，Codex 立刻恢复正常。今天就把这次踩坑经历和排查过程分享出来，希望能帮到遇到类似问题的朋友。

二、问题现象

我的环境是这样的：

• 操作系统：Windows 11
• Codex 版本：Microsoft Store 最新版 Codex Windows 桌面客户端
• 问题项目：DeusData/codebase-memory-mcp

安装 codebase-memory-mcp 后，打开 Codex 桌面版，界面始终卡在“Complete Windows Setup”页面，提示 “Windows 安装未完成” 。无论点击“重试 Windows 设置”还是“继续受限访问”，都没有任何反应。即使用管理员权限运行，问题依旧。

关键线索：当我卸载/删除 codebase-memory-mcp 相关文件后，Codex 重新打开，一切恢复正常。这说明问题不是 Codex 本身坏了，而是 codebase-memory-mcp 的安装过程对 Codex 的某些配置造成了破坏。

三、排查过程

3.1 第一反应：Windows 环境问题

看到“Windows 安装未完成”这个提示，第一反应自然是检查 Windows 本身：

• ✅ 检查 AppX 包是否安装成功
• ✅ 检查 Windows App Runtime 状态
• ✅ 检查 AppXSvc 和 ClipSVC 服务
• ✅ 检查应用是否真正启动

结果发现：Windows 已经成功完成了应用启动。问题不在 Windows 这边。

3.2 查看 Codex 客户端日志

真正有用的线索藏在 Codex 的客户端日志里：

C:\Users\<用户名>\AppData\Local\Packages\OpenAI.Codex_xxxxx\

日志中反复出现这样的错误：

failed to reload config: C:\Users\<用户名>\.codex\config.toml duplicate key
failed to read configuration layers duplicate key
Invalid TOML document

真相大白：C:\Users\<用户名>\.codex\config.toml 这个配置文件坏了！

3.3 为什么重装 Codex 没用？

很多人遇到这种情况会反复卸载重装 Codex，但重装完全没用。原因在于：

Codex 的用户配置文件（config.toml）不会被卸载程序删除。重装后，Codex 读取的仍然是那个已经损坏的配置文件。

四、根因分析：codebase-memory-mcp 做了什么？

codebase-memory-mcp 的 install 命令号称能“自动检测所有已安装的编码代理，并为每个代理配置 MCP 服务器条目”。它支持包括 Codex CLI 在内的 11 种 AI 编码代理。

问题就出在这里：

1. 自动修改配置文件：codebase-memory-mcp 的安装过程会向 ~/.codex/config.toml 写入 MCP 服务器配置。
2. TOML 格式问题：Codex 的配置文件使用 TOML 格式。如果写入的内容格式不正确（比如重复的 key、编码异常等），就会导致整个 TOML 文档失效。
3. 初始化流程卡死：Codex 启动时需要读取 config.toml 完成 MCP 初始化。一旦配置文件损坏，初始化失败，界面就卡在“Windows 安装未完成”。

简单来说：codebase-memory-mcp 修改了 Codex 的配置文件，但修改方式与当前 Codex 版本不兼容，导致配置文件损坏。

五、解决方案

方案一：删除配置文件（推荐）

直接删除（或重命名）Codex 的配置文件，让 Codex 自动重新生成一个干净的版本：

# 备份旧配置（可选）
ren C:\Users\<你的用户名>\.codex\config.toml config.toml.bak
或者直接删除
del C:\Users&lt;你的用户名>.codex\config.toml

然后重新打开 Codex，它会自动生成新的配置文件，问题即可解决。

方案二：手动修复 TOML 配置

如果你确实需要使用 codebase-memory-mcp，可以尝试手动编辑 config.toml，确保其格式正确：

[mcp_servers.memory]
command = "codebase-memory-mcp" # 或完整的可执行文件路径
args = ["serve"]

检查是否有重复的 key、编码异常等问题。

方案三：隔离配置环境

如果经常需要在不同 MCP 工具间切换，可以考虑使用环境变量隔离配置：

$env:CODEX_HOME = "C:\Users\<用户名>\.codex_dev"
codex

这样可以避免不同工具互相干扰。

六、经验总结

这次踩坑让我深刻体会到几个道理：

1. “Windows 安装未完成”≠ Windows 有问题

这个提示极具误导性。实际上，Windows 早就完成安装了，出问题的是 Codex 客户端的内部初始化。

2. 自动配置工具是把双刃剑

codebase-memory-mcp 的“一键安装、自动配置”看起来很美好，但如果配置逻辑与目标客户端版本不完全兼容，就可能造成灾难性后果。

3. 配置文件是“隐形杀手”

很多 AI 工具（Codex、Claude Code、Cursor 等）的配置文件都藏在用户目录下，重装软件时不会被清除。排查问题时，优先检查配置文件往往比反复重装更高效。

4. 社区已有类似案例

其实类似的问题在社区并不少见——MCP 服务器与 Codex 的配置兼容性问题已经有多个 Issue 被报告。遇到问题时多搜搜 GitHub Issues，往往能少走很多弯路。

---

如果你也在 Windows 上使用 Codex 并遇到了“Windows 安装未完成”的提示，不妨先检查一下 C:\Users\<用户名>\.codex\config.toml 是否完好。很多时候，删掉它，重启 Codex，世界就清净了。

希望这篇文章能帮到你。如果觉得有用，欢迎点赞、收藏、评论三连！

---

本文首发于 CSDN，未经授权禁止转载。