我花 3 天踩的坑，帮你 1 小时全避开——Codex 知识库搭建避坑实录
一只阿木木约 7 分钟🪝
上一篇我写了「10 分钟搭好 AI 知识库」的保姆教程。
评论区里排名第一的问题是：
"我按着步骤做了，但感觉没什么用？"
我懂这种感觉。我第一次搭完的那晚，也觉得「好像还是一堆文件夹？」
区别不在于步骤有没有做完，而在于几个关键细节。
我花了整整 3 天时间把该踩的坑全踩了一遍，才找到那个「对」的感觉——知识库开始参与我的思考，而不只是帮我存东西。
这篇文章，我把我踩的 7 个真实的坑 全部写出来，帮你在搭建阶段就绕开它们。
「我花 3 天踩的坑，你 1 小时读完就全避开了。这是知识库该有的样子——别人的经验，直接变成你的资产。」
坑 #1：把 Vault 放在了云同步盘里
我当时怎么做的： 第一个直觉是把 Obsidian Vault 建在 iCloud 或百度网盘同步的文件夹里——感觉这样更安全。
结果发生了什么： MCP 服务在初始化索引的时候，反复读写大量 .md 文件，触发了云同步冲突。Obsidian 里开始出现 笔记名 (conflicted copy).md 这样的重复文件，把我好几条笔记弄乱了。
正确做法：
text
✅ 把 Vault 放在本地纯路径，不要放在实时同步的云盘文件夹里
✅ 如果需要备份，用 Git 做版本控制（每次修改都有记录，出问题可以回滚）
✅ 如果一定要跨设备同步，用 Obsidian Sync 官方服务（它和 MCP 是兼容的）
一行命令搞定 Git 初始化：
Bash
cd /你的Vault路径/MyBrain
git init
git add .
git commit -m "init: 知识库初始化"
以后每次让 Codex 修改完笔记，加一句"帮我提交一下这次修改"，它会自动帮你做 git commit，留下变更记录。
坑 #2：AGENTS.md 写得太空洞
我当时怎么做的：
我的第一版 AGENTS.md 只有两行：
Markdown
# 我的知识库
请帮我整理笔记。
结果发生了什么：
Codex 每次给我的结果都很「通用」——它不知道我在做什么领域、不知道我的笔记结构、不知道我的输出偏好。它给的建议像在给所有人建议，没有我的味道。
3 只写 AGENTS.md 知道在哪里，不一定等于任何项目都能直接写入，更不等于 AI 真正理解你的工作方式。
正确做法：
AGENTS.md 越具体越好。以下是我第三版迭代后的关键字段，你可以直接照抄框架：
Markdown
## 关于我
- 我是一个内容创作者/知识工作者（改成你自己的身份）
- 我目前关注的核心领域：个人成长、AI工具、PKM
- 我的输出目标：公众号文章、B站视频脚本、Obsidian知识页## 笔记结构规范
- Inbox/ 是原始输入，不要要求格式
- raw/ 是整理一遍后的资料，需要有 frontmatter
- wiki/ 是成熟知识，修改前请告知## 我的写作偏好
- 中文输出，口语化但不随意
- 先给结论，再展开论据
- 每个概念给我一句话版本 + 详细版本
- 我不喜欢"你应该..."的语气，请用"一种方式是..."## 什么时候需要问我确认
- 删除任何已有内容之前
- 创建新文件夹之前
- 修改 wiki/ 下的成熟知识页之前
写 AGENTS.md 的核心原则：
想象你在给一个刚入职的助理写「工作手册」。写得越具体，它犯错的概率越低，输出越符合你的预期。
坑 #3：一开始就想整理全库
我当时怎么做的：
搭好系统的第一件事，我对 Codex 说："帮我整理 Obsidian 里所有的笔记。"
结果发生了什么：
它开始处理，然后处理了很久，然后输出了一堆「建议」，但什么也没真正改变。因为命令太模糊、范围太大，Codex 不知道从哪里下手。
正确做法：
第一周，只处理 Inbox 里的新笔记。
不要碰旧笔记。先让系统在「小范围」跑顺了，再逐渐扩大边界。
具体命令这样写：
text
❌ 错误：帮我整理所有笔记
✅ 正确：读取 Inbox/ 文件夹下今天新建的笔记，
帮我提炼核心观点，在 raw/ 下创建摘要页，
并检查 wiki/ 下是否有可以关联的已有笔记
越具体，结果越好。给 AI 的命令，要像给人的工作说明书一样具体。
坑 #4：忘记验证「写入权限」
我当时怎么做的：
MCP 启动后我直接开始用，但发现 Codex 说"已经帮你整理好了"，但 Obsidian 里什么变化都没有。
结果发生了什么：
我没有加 --enable-write 参数——MCP 默认是只读模式。Codex 以为自己在写文件，其实什么都没写。我白高兴了半天。
正确做法：
启动 MCP 服务时，一定要确认参数：
Bash
enquire-mcp serve --vault /你的路径 \
--persistent-index \
--enable-write ← 这行不能少
同时，搭建完成后做一个「写入验证测试」：
text
在 Inbox/ 新建一个测试笔记，内容随意。
然后对 Codex 说：读取 Inbox/ 下的 test.md，
在 raw/ 下为它创建一个摘要页，命名为 test-summary.md。
如果 raw/ 下出现了新文件，恭喜，写入权限正常。
坑 #5：Frontmatter 格式不统一
我当时怎么做的：
旧笔记里有些有 frontmatter，有些没有。有些用的是 created，有些用的是 date，有些没有 tags 字段。
结果发生了什么：
Codex 在跨笔记做关联分析时，因为 metadata 不统一，找不到很多本来应该被关联的笔记。知识图谱里有大量孤立节点。
正确做法：
在 AGENTS.md 里定义统一的 Frontmatter 规范，并让 Codex 帮你补全旧笔记：
Markdown
## Frontmatter 规范
所有正式笔记（raw/ 和 wiki/）必须包含以下字段：---
date: YYYY-MM-DD
tags: [标签1, 标签2]
status: draft / reviewing / published
source: 来源链接或书名（如有）
---
批量修复命令：
text
读取 raw/ 下所有没有 frontmatter 的笔记，
按照 AGENTS.md 里定义的 Frontmatter 规范，
为每个文件补全 frontmatter，日期用文件的创建日期。
坑 #6：把 raw 和 wiki 混在一起
我当时怎么做的：
懒得分文件夹，什么笔记都往一个文件夹放。
结果发生了什么：
三个月后，文件夹里有 200 多个文件，一半是没整理完的草稿，一半是还不错的笔记，完全分不清哪些是「可以被引用的知识」，哪些是「需要继续消化的原材料」。
知识库变成了一个更大的收藏夹坟场。
正确做法：
5 知识库不再只吸收新资料，也开始吸收新问题——这才是一个系统会持续长起来的信号。
而这个信号的前提，是你的系统有清晰的层级：
text
Inbox/ → 今天的输入，质量不限
↓（Codex 处理后）
raw/ → 结构化的资料，有 frontmatter，质量中等
↓（反复提炼，手动确认）
wiki/ → 成熟知识，可被引用，质量高
这三层不能混。 分层是整个系统能够「自生长」的结构基础。
坑 #7：没有定期「检查系统健康度」
我当时怎么做的：
搭好系统之后，我以为它会自己一直好好运转，就没管它了。
结果发生了什么：
两周后我发现 MCP 服务因为重启电脑而停掉了，但我没发现，一直在对着 Codex 说话，但它其实在没有 Vault 权限的情况下靠「凭空想象」回答我。输出的笔记全是假的。
正确做法：
每周做一次「系统健康检查」，只需要一个命令：
text
列出 Inbox/ 下超过 3 天未处理的笔记，
列出 raw/ 下标记为 draft 且超过 2 周未更新的笔记，
告诉我 wiki/ 下有哪些孤立页面（没有被任何其他笔记链接）。
把这个命令保存成一个 Skill，每周一自动执行一次。你的知识库就有了「自我体检」的能力。
📊 7 个坑的速查总结
🔮 下一步
避开了这 7 个坑，你的知识库已经比 95% 的人搭的都要稳了。
但一个「稳」的系统，和一个「自运转」的系统，还差最后一个关键的东西：
你需要一份真正懂你的 AGENTS.md。
下一篇我会把我迭代了 5 个版本的 AGENTS.md 完整公开，带你一行行搞懂每个字段的意义——以及为什么它是整个知识库系统的灵魂。
「系统搭好了但感觉没用，99% 的原因都在 AGENTS.md 上。这不是工具的问题，是规则写得不够具体。」
普通人如何用 AI 搭建自己的知识操作系统？
一个程序员出身的知识工作者，公开记录自己如何用 AI 工具搭建个人知识系统、把读过的书和做过的项目变成可复用资产的全过程。
我是【一只阿木木】——公开建造我的 AI 第二大脑。
我们的方向是——AI + Obsidian 的结合。但请记住：Obsidian 的灵魂不是效率，是自由。不是自动化，是代理力。不是工具帮你想，而是你借工具想得更好。
在一个许多工具承诺代替用户思考的市场中，Obsidian 赌的是我们仍然想要一个可以自己思考的地方。 欢迎加入行动营👇
获取更多Obsidian + AI数字大脑实践
我相信：在 AI 时代，每个普通人都该拥有一个自动生长的知识系统
欢迎关注【一只阿木木】🌊