1. 为什么要把 Codex 和 Obsidian 接在一起很多人用 AI 写代码、写文档用得很爽但有个问题一直没解决每次对话都是从零开始。你上周跟 AI 讨论过的项目架构、踩过的坑、定下来的命名规范这周开个新会话它全忘了。你得重新贴一遍背景重新解释一遍约束效率低得让人抓狂。我自己就吃过这个亏。手头同时维护三个项目每个项目的技术栈、目录结构、代码风格都不一样。每次切换项目光是给 AI 交代背景就要花十几分钟而且交代完它还不一定记得住。后来我想明白一件事AI 缺的不是能力是记忆。它需要一个地方存放你的积累然后在每次干活前自动读取。这就是 Codex 加 Obsidian 这套组合的核心价值。Obsidian 负责当外置大脑把你的项目笔记、规范文档、历史决策全部结构化地存起来Codex 负责当执行手在动手之前先读一遍这些积累然后接着你的思路往下干。两者之间靠一个叫AGENTS.md的文件牵线搭桥再配合index.md做知识索引整个流程就串起来了。这套方案适合谁我总结了三类人。第一类是独立开发者一个人扛几个项目脑子不够用需要外部记忆。第二类是技术团队的小 leader要把团队规范沉淀下来让 AI 辅助时自动遵守。第三类是知识工作者平时用 Obsidian 记笔记想让 AI 基于自己的笔记库回答问题、写东西而不是基于它自己的通用知识瞎编。说白了这套东西解决的是AI 如何继承你的上下文这个问题。下面我把整套流程拆开讲从环境准备到跑通第一个自动化任务每一步都给你说清楚。2. 环境准备Codex 和 Obsidian 各自怎么装2.1 Codex 的安装与登录避坑Codex 目前主流的用法是 CLI 版本也就是命令行工具。Windows 用户直接去官网下载安装包Mac 和 Linux 用户可以用包管理器装。我实测下来Windows 桌面版安装最省事双击一路下一步就行但要注意安装路径别带中文和空格否则后面调用的时候容易出莫名其妙的错误。安装完之后第一件事是登录。这里有个高频问题手机号验证收不到码。我试过几次发现是运营商拦截了国际短信换个时间段重试或者改用邮箱登录就能绕过。如果你登录时一直卡在正在重新连接大概率是网络环境的问题检查一下代理设置确保终端能正常访问外网。登录成功之后建议先跑一个codex --version确认版本再跑codex --help看看有哪些子命令。很多人装完就急着用结果连基本命令都没摸清楚后面出问题排查起来很痛苦。关于中文设置Codex 本身支持中文交互但有个坑设置中文之后不生效。原因是配置文件里的语言字段没写对你需要手动去配置文件里把language改成zh-CN然后重启终端。如果还是不行检查一下是不是有多个配置文件冲突了Codex 会优先读取用户目录下的那个。2.2 Obsidian 的下载与基础配置Obsidian 的下载没什么难度官网直接下对应平台的安装包。装完之后第一件事是建库也就是创建一个 vault 文件夹。这个文件夹就是你所有笔记的根目录建议放在一个固定的、路径简单的位置比如D:\KnowledgeBase或者~/Documents/MyVault别放在桌面或者下载文件夹里容易误删。建完库之后我强烈建议先装两个插件Dataview和Templater。Dataview 让你能用类 SQL 的语法查询笔记Templater 让你能定义模板自动生成笔记结构。这两个插件是后面做知识索引的基础不装的话index.md就只能手动维护累死人。主题方面Anuppuccin 是很多人推荐的但安装时经常提示无法安装。这个问题的根源是网络访问 GitHub 不稳定解决办法是手动下载主题包解压到 vault 的.obsidian/themes/目录下然后在设置里启用。别在这个问题上耗太久默认主题完全够用先把流程跑通再说。标签系统是 Obsidian 的另一个重点。很多人不知道怎么加标签其实很简单在笔记正文里输入#标签名就行或者在 frontmatter 里写tags: [标签1, 标签2]。我建议统一用 frontmatter 的方式因为这样标签和正文分离后面用 Dataview 查询的时候更干净。2.3 目录结构设计让 AI 能读懂你的知识库这一步是整套方案的地基很多人跳过这步直接上工具结果 AI 读了一堆乱七八糟的笔记输出质量惨不忍睹。我的建议是按项目-类型-时间三层结构来组织KnowledgeBase/ ├── AGENTS.md # AI 入口文件 ├── index.md # 全局知识索引 ├── projects/ │ ├── project-a/ │ │ ├── README.md # 项目概述 │ │ ├── decisions.md # 关键决策记录 │ │ ├── conventions.md # 编码规范 │ │ └── notes/ # 日常笔记 │ └── project-b/ ├── snippets/ # 可复用代码片段 ├── references/ # 外部资料摘录 └── daily/ # 日记流水这个结构的关键在于每个项目都有固定的几个文件README 说清楚项目是干什么的decisions 记录为什么这么设计conventions 定死代码风格。AI 读这三个文件基本就能理解项目的全貌不需要你每次重新解释。注意目录名和文件名尽量用英文避免中文路径在某些终端环境下出现编码问题。笔记内容用中文完全没问题只是路径建议英文。3. AGENTS.md 和 index.md整套方案的核心机关3.1 AGENTS.md 到底该写什么AGENTS.md是 Codex 的入口文件它会在每次启动时自动读取这个文件的内容作为系统提示的一部分。你可以把它理解成给 AI 的一份工作说明书。写得好AI 就像你的老搭档写得烂AI 就是个只会说套话的实习生。我踩过的坑是一开始把 AGENTS.md 写成了大杂烩什么信息都往里塞结果 AI 反而抓不住重点。后来我总结出一个原则AGENTS.md 只写元信息和路由规则具体知识放到各个项目文件里。一个可用的 AGENTS.md 模板长这样# 工作说明 ## 身份 你是一个资深开发助手服务于我的个人知识库。 ## 知识库位置 根目录D:\KnowledgeBase 索引文件index.md ## 工作流程 1. 接到任务后先读 index.md 定位相关项目 2. 读取对应项目的 README.md、decisions.md、conventions.md 3. 基于以上上下文执行任务 4. 任务完成后把新的决策和笔记写回对应文件 ## 约束 - 代码风格遵循 conventions.md - 不确定的地方先问我不要瞎猜 - 输出用中文代码注释也用中文这个模板的核心是第 2 步和第 4 步。第 2 步让 AI 主动去读上下文第 4 步让 AI 把新产生的知识写回去形成闭环。没有这个闭环你的知识库永远是静态的AI 用一次就忘一次。3.2 index.md 的索引设计index.md是知识库的目录作用是让 AI 快速定位到相关文件而不是把整个库都读一遍。如果库很大全读一遍既慢又浪费 token所以索引必须精准。我的做法是用 Dataview 自动生成索引而不是手动维护。在 index.md 里写一段查询TABLE project, type, updated FROM projects WHERE type readme OR type decisions SORT updated DESC这样每次打开 index.md它都会自动列出所有项目的核心文件。AI 读这个索引就知道有哪些项目、每个项目的核心文件在哪然后按需读取。如果你不想用 Dataview手动维护也行但要养成习惯每新建一个项目就在 index.md 里加一行。我见过太多人建了一堆项目文件结果 index.md 还是空的AI 根本不知道这些文件存在。3.3 两者的配合逻辑把 AGENTS.md 和 index.md 的关系理清楚AGENTS.md 是怎么干活的说明书index.md 是有什么活可干的清单。AI 启动时先读 AGENTS.md 知道流程然后按流程去读 index.md 知道有哪些项目再按索引去读具体项目文件获取细节。这个三层结构的好处是可扩展。你新增一个项目只需要在 projects 下建文件夹、写三个核心文件、在 index.md 里加一行AI 下次就能自动识别。不需要改 AGENTS.md也不需要重新训练什么模型。提示AGENTS.md 和 index.md 都放在知识库根目录Codex 启动时把工作目录设成知识库根目录它就能自动找到这两个文件。4. 实操从零跑通第一个自动化任务4.1 初始化知识库并接入 Codex假设你已经装好了 Codex 和 Obsidian现在从零开始。第一步在 Obsidian 里建好前面说的目录结构把 AGENTS.md 和 index.md 写好。第二步打开终端cd 到知识库根目录运行codex启动。启动后Codex 会自动读取当前目录下的 AGENTS.md。你可以先问它一句你现在知道我的知识库结构吗如果它能把目录结构和索引文件说出来说明接入成功。如果它一脸茫然检查一下 AGENTS.md 是不是放在了正确的位置以及 Codex 的工作目录是不是知识库根目录。这一步我建议多试几次确认 AI 真的读到了文件。有时候路径里有空格或者特殊字符会导致读取失败但 Codex 不一定报错只是默默忽略。所以一定要用提问的方式验证。4.2 写第一个项目笔记并让 AI 读取现在建一个测试项目。在projects/下新建demo-project/写三个文件README.md写项目是干什么的--- project: demo-project type: readme updated: 2025-01-15 --- # Demo Project 这是一个用于测试 Codex 接入的示例项目。 技术栈Python 3.11 FastAPI 主要功能提供一个简单的用户管理 APIdecisions.md写关键决策--- project: demo-project type: decisions updated: 2025-01-15 --- # 关键决策 ## 为什么用 FastAPI 而不是 Flask - 需要自动生成 OpenAPI 文档 - 需要异步支持 - 类型提示更友好conventions.md写编码规范--- project: demo-project type: conventions updated: 2025-01-15 --- # 编码规范 - 函数名用 snake_case - 类名用 PascalCase - 所有公开函数必须有 docstring - 错误处理统一用自定义异常写完这三个文件回到 Codex问它demo-project 用的是什么技术栈为什么选 FastAPI如果它能准确回答说明读取链路通了。4.3 让 AI 基于积累生成代码这是最有价值的一步。你让 Codex 给 demo-project 加一个新接口比如用户注册。它应该先读 conventions.md 知道命名规范再读 decisions.md 知道技术选型然后生成符合规范的代码。我实测下来生成的代码质量比直接让 AI 写要高一个档次因为它知道了你的约束。比如它会自动用 snake_case 命名函数自动加 docstring自动用自定义异常处理错误。这些细节如果每次都要你手动交代累都累死了。生成完之后让 AI 把这次的新决策写回 decisions.md。比如注册接口用了 bcrypt 加密密码因为……这样下次再做相关功能它就知道密码加密用的是什么方案。4.4 验证闭环是否跑通闭环的验证标准很简单新开一个 Codex 会话问它上次做了什么决策看它能不能答上来。如果能说明知识写回成功了如果不能检查写回的文件路径对不对以及 index.md 有没有更新。我建议每次做完一个任务都花一分钟检查一下知识库有没有更新。这个习惯养成了你的知识库会越来越厚AI 会越来越懂你。反过来如果只读不写知识库永远是那几页AI 永远是个新人。5. 常见问题与排查技巧实录5.1 Codex 连接与登录类问题问题现象可能原因解决办法一直显示 reconnecting网络不稳定或代理配置错误检查终端网络确认能访问外网手机号收不到验证码运营商拦截国际短信换邮箱登录或换时间段重试登录不上提示组织设置错误账号权限或配置问题检查配置文件确认账号状态设置中文不生效配置文件语言字段未改手动改language: zh-CN并重启无法加载组织设置配置文件损坏删除配置重新登录这些问题我基本都遇到过最烦的是一直 reconnecting排查了半天发现是代理没配对。所以遇到连接问题第一件事就是确认网络环境别急着怀疑软件本身。5.2 Obsidian 插件与主题类问题Anuppuccin 主题装不上是最常见的根源是 GitHub 访问不稳定。手动下载主题包解压到.obsidian/themes/目录然后在设置里启用基本都能解决。Dataview 和 Templater 这两个插件建议用 Obsidian 内置的社区插件市场装如果市场打不开同样手动下载解压到.obsidian/plugins/。标签不生效的问题多半是写法不对。记住frontmatter 里的标签用tags: [a, b]正文里的标签用#a两者不能混用。混用的话 Dataview 查询会漏掉一部分。5.3 AI 读取知识库失败类问题AI 读不到文件最常见的原因是工作目录不对。Codex 启动时的工作目录决定了它能访问哪些文件如果你在别的目录启动它自然读不到知识库。解决办法是每次启动前先 cd 到知识库根目录或者用codex --cwd D:\KnowledgeBase指定目录。另一个原因是文件编码问题。如果笔记文件是 GBK 编码Codex 可能读出来是乱码。统一用 UTF-8 编码这个问题就没了。Obsidian 默认就是 UTF-8但如果你从别的地方导入笔记要注意转换。5.4 我的独家避坑心得第一条别把敏感信息写进知识库。AGENTS.md 和项目笔记会被 AI 读取如果你在里面写了密码、密钥、内部地址等于把这些信息交给了 AI。我建议单独建一个secrets/目录在 AGENTS.md 里明确告诉 AI 不要读这个目录。第二条知识库要定期备份。Obsidian 的库就是一个文件夹用 Git 管理最方便。每次写完笔记 commit 一下出问题能回滚。我见过有人库文件损坏几年的笔记全没了哭都来不及。第三条别追求一次到位。很多人想把知识库建得完美无缺再开始用结果永远开始不了。我的做法是先建最小可用版本用起来遇到问题再补。知识库是长出来的不是设计出来的。第四条AI 写回的内容要人工审核。AI 有时候会理解错你的意思把错误的决策写进 decisions.md。如果不审核错误会累积后面 AI 基于错误信息做决策越走越偏。每次写回后花几十秒扫一眼能省很多事。6. 进阶玩法让知识库真正活起来6.1 用 Dataview 做动态看板知识库大了之后光靠 index.md 不够用。我建议做一个 dashboard 笔记用 Dataview 查询各种维度的信息。比如最近一周更新的项目、所有待办事项、所有标记为重要的决策。这样打开 Obsidian 就能看到全局状态不用一个个文件夹翻。Dataview 的查询语法不难核心就是FROM指定范围、WHERE过滤条件、SORT排序、TABLE或LIST决定展示形式。花半小时看官方文档就能上手投入产出比很高。6.2 把日常笔记自动归档到项目平时用 Obsidian 记笔记很多是零散的散落在 daily 目录里。我写了一个简单的脚本每天定时把 daily 里的笔记按关键词归类到对应项目。比如笔记里提到 demo-project就自动复制一份到projects/demo-project/notes/下。这个脚本用 Python 写核心就是读文件、匹配关键词、复制文件。不复杂但能省很多手动整理的时间。归类之后AI 读项目笔记时就能看到这些日常积累上下文更完整。6.3 多项目切换时的上下文管理同时维护多个项目时最大的问题是上下文混淆。AI 可能把 A 项目的规范用到 B 项目上。解决办法是在 AGENTS.md 里明确写每次任务开始前确认当前项目是哪个只读取该项目的文件。另外我建议给每个项目单独开一个 Codex 会话别在一个会话里来回切换项目。会话隔离能避免上下文污染虽然麻烦一点但输出质量更稳定。6.4 知识库的长期维护策略知识库用久了会膨胀需要定期清理。我的做法是每月做一次知识库体检删掉过时的笔记合并重复的内容更新 index.md。体检完之后AI 读取的效率会明显提升。还有一个技巧是给笔记加有效期字段。比如某个决策是临时的就标上expires: 2025-06-01到期后 Dataview 查询会把它标红提醒你处理。这样知识库不会积累一堆过时信息。7. 我个人的一些体会这套方案我用了一年多最大的感受是AI 的上限取决于你给它的上下文。同样的模型喂给它一个结构化的知识库和让它从零开始输出质量差得不是一点半点。很多人抱怨 AI 不好用其实问题往往出在自己这边——你没给它足够的背景信息。另一个体会是知识库的价值在于持续积累。刚开始用的时候库是空的AI 帮不上什么忙。但用了一个月、三个月、半年之后库里的决策、规范、笔记越来越多AI 越来越懂你的项目效率提升是指数级的。所以别指望立竿见影要坚持用。最后分享一个小技巧把 AI 的每次输出都当成一次知识沉淀的机会。它生成的代码、写的文档、做的决策只要有价值就写回知识库。这样你的库会随着使用不断增厚形成一个正向循环。用久了你会发现这个库不只是给 AI 用的也是给你自己用的——它就是你项目的完整记忆。