把 Obsidian 和 Codex 拼在一起用是我最近折腾得最值的一件事。一边写技术笔记一边想让 AI 帮忙检查思路、补代码片段传统做法是切到浏览器或终端再开一个对话框来回切换不仅打断思路对话记录也容易丢。这篇文章就给你一份 Windows 上的保姆级配置教程让 Codex 对话直接发生在 Obsidian 里——你可以把它当作笔记中的一个面板随时唤起、随时记录。先说清楚一件事这教程不是什么底层魔改而是把已经成熟的工具串起来。Obsidian 负责内容存储和编辑Codex 负责对话和生成代码中间通过两种方式连接一种是内嵌终端直接运行 Codex CLI另一种是用聊天插件调用 Codex 背后的模型 API。两种方案我都实际跑过各有优劣后面会分开讲你可以按自己的网络情况和动手能力选择。如果你刚接触 Obsidian也没用过 Codex跟着一步步走也能配通。1. 动手之前先分清“Codex 对话”的两种形态1.1 Codex 到底是什么很多人听到 Codex第一反应是 OpenAI 的某个代码模型。在 2025 年的语境下Codex 更像是一个能自主跑命令、读写文件、在终端里完成任务的 AI 助手。它有一个叫codex的命令行工具你输入自然语言需求它会把需求拆解成工具调用自己执行代码、看结果、继续修正直到完成目标。日常使用中最常见的交互就是“对话”你问它问题它给出方案你进一步追问它继续补充。在 Windows 上Codex 有两种常见安装形态一种是 npm 包openai/codex装好后在 PowerShell 或 CMD 里敲codex就能进入对话另一种是带图形界面的桌面版安装包适合不习惯命令行的朋友。本文的“方案 A”会以内嵌终端的思路让两种形态都能在 Obsidian 里用起来。1.2 在 Obsidian 里用 Codex本质上是解决“入口”问题你想在 Obsidian 里用 Codex核心痛点不是“Codex 怎么装”而是“我怎么不用切窗口就能和它对话”。Obsidian 本身只是个 Markdown 笔记软件默认没有聊天窗口也没法直接连接外部 AI。所以要做的就是给 Obsidian 加一个“入口”。我踩过几条路之后归纳出两种用得最顺手的方式方案实现方式适合场景配置难度体验评价方案 AObsidian 内嵌终端 本地 Codex CLI重度 CLI 用户、要让它执行本地代码和文件操作中最接近“真 Codex”但窗口观感朴素方案 BObsidian 聊天插件 模型 API主要想用 AI 对话补全笔记、续写内容较低界面更像聊天软件但无法直接操作本地文件方案 B 里说的“模型 API”本质上是让插件直接请求 OpenAI 兼容的模型接口。如果你的 Codex 账号已经具备相应模型访问权限可以用 API Key 的方式让插件走同一套模型如果只是想体验对话补全也可以独立配置 OpenAI API。两条路不冲突甚至可以同时存在。2. Windows 环境准备装对工具后面少踩坑在正式配置之前得先把基础环境理一遍。我见过太多人卡在“第一步下载慢”或者“node 没装对”后面跑不起来还以为 Codex 有问题。其实 Windows 下的准备工作很固定按顺序来就好。2.1 安装 Obsidian下载慢怎么破Obsidian 官方安装包通常会在浏览器里触发海外下载国内网络环境下确实可能慢。我试过最省心的办法是打开微软商店直接搜“Obsidian”安装微软商店版本。这样安装速度快更新也由系统自动管理不会出现“安装包一直转圈”的情况。如果还是想用官网安装包可以注意一下安装包的后缀。官网提供.exe安装版和.zip便携版。便携版无需安装解压到任意目录双击Obsidian.exe就能用适合放在移动硬盘里。下载慢的时候可以换个时间段重试或者用迅雷等支持多线程的下载工具但我个人最推荐的还是微软商店版本稳定省事。2.2 安装 Git for Windows不是必需但建议装很多 Obsidian 插件教程会强调安装 Git因为如果你想用 BRAT 插件从 GitHub 仓库直接安装测试版插件系统里得有 Git。但如果你只用社区插件市场的现成插件不自己折腾源码Git 其实不是硬性要求。不过Codex 这类工具在 Windows 上运行时有时会调用git命令来分析仓库状态。所以我还是建议装上。去 Git 官网下载 Windows 版安装包一路下一步即可唯一要注意的是安装到“选择默认编辑器”那一步建议选“Use Visual Studio Code as Gits default editor”如果你装了 VS Code 的话没装就直接用默认 Vim 也行。装完后打开 PowerShell输入git --version能返回版本号就说明环境变量配置成功。2.3 安装 Node.js跑 Codex CLI 的必要条件Codex CLI 的 npm 包依赖 Node.js 运行时而且要求版本较高。我用的是 Node.js 20 LTS跑得没问题。建议不要图新装 22 以上的奇数版本LTS 版本在兼容性上更稳妥。去 Node.js 官网下载 Windows 安装包.msi双击安装。安装过程中保持默认选项即可它会自动把 Node 和 npm 加入系统 PATH。安装完成后重新打开一个 PowerShell 窗口输入node -v npm -v两个命令都能输出版本号说明环境 OK。这一步很关键因为后面npm install -g openai/codex能不能全局识别完全看这里。2.4 获取 OpenAI API Key 或 Codex 授权方案 B 需要 API Key方案 A 的codex命令也需要完成登录认证。你可以选择两种认证方式之一在 Codex CLI 里执行codex login通过浏览器完成 OAuth 授权这种方式依赖浏览器登录态。更通用的是创建一个 API Key设置成环境变量OPENAI_API_KEY这样命令行工具和插件都能读取。API Key 的获取位置在 OpenAI 官方平台的个人中心进入 API Keys 页面点击创建新密钥复制后保存好。这里有一个很容易踩的坑密钥只会在创建时完整显示一次关闭页面后就再也看不到了所以一定要先粘贴到本地文本里暂存。Windows 下配置环境变量的操作路径是设置 → 系统 → 关于 → 高级系统设置 → 环境变量。在“用户变量”里新建一项变量名填OPENAI_API_KEY变量值填你的密钥确认保存后重新打开终端才会生效。2.5 确认网络能访问 OpenAI 服务这一步比较敏感我不展开讲那些额外工具。你只需要知道无论是 Codex CLI 还是聊天插件都要去访问 OpenAI 的 API 服务。如果网络不通后面会报各种链接失败、请求超时的错。建议在安装之前先做一次连通性测试curl https://api.openai.com/v1/models -H Authorization: Bearer $env:OPENAI_API_KEY如果返回 JSON 数据说明网络通畅、密钥有效如果卡住或报错先处理基础网络和防火墙问题再继续配 Codex否则会白白折腾几个小时。3. 方案 A在 Obsidian 内嵌终端直接跑 Codex CLI这个方案是我目前在用的主力方式。它不依赖任何聊天插件直接把一个终端窗口嵌在 Obsidian 的面板里然后在终端里运行 Codex。这样 Codex 的每一次输出都发生在 Obsidian 界面内旁边就是你的笔记想抄代码片段直接选中复制非常自然。3.1 安装 Codex CLI 的两种方式第一种是用 npm 全局安装打开 PowerShell 执行npm install -g openai/codex装完后执行codex --version如果显示版本号说明安装成功。这种方式后续更新也方便直接再执行一遍同样的命令即可覆盖升级。如果你更习惯图形界面也可以去 Codex 的 GitHub Releases 页面找 Windows 桌面版安装包。下载.exe文件后双击安装按 Win 键搜索“Codex”就能打开。桌面版自带聊天界面但想要嵌进 Obsidian本质上还是要靠终端模拟器来调用。所以本文后续都以命令行版为准。3.2 登录 Codex从环境变量到认证检查推荐最省心的环境变量方式。按前面 2.4 节把OPENAI_API_KEY设置好然后在终端里验证codex exec say hello in one sentence这条命令会让 Codex 以非交互模式执行一次简单任务。如果正常返回一句话说明认证已经通过。如果你用的是 OAuth 登录会多一个浏览器授权步骤整体也不复杂。这里有个细节要注意Codex CLI 的配置文件在%USERPROFILE%\.codex\config.toml。如果你想切换模型可以打开这个文件在[model]段或对应位置修改模型 ID。默认值通常是官方给 Codex 指定的模型建议保持默认除非你明确知道自己在做什么。3.3 在 Obsidian 中安装 Terminal 插件Obsidian 的社区插件市场里有一个叫“Terminal”的插件作者是 polyipseity。它能在 Obsidian 的标签页里打开一个真实的终端窗口支持 PowerShell、CMD、WSL 等多个 shell。安装步骤打开 Obsidian → 设置 → 第三方插件。关闭“安全模式”Restricted mode。点击“浏览”进入社区插件市场。搜索“Terminal”找到作者为 polyipseity 的那个点击安装。安装完成后点击“启用”。启用后按CtrlP打开命令面板输入“Terminal: Open new terminal”回车你会看到 Obsidian 里多出一个终端标签页。如果是第一次运行插件会问你要用哪个 shellWindows 上选PowerShell或cmd都可以。我之前用 PowerShell 遇到过一次字体发虚的问题后来在插件设置里把字体改成Cascadia Mono就正常了。3.4 在终端标签页里启动 Codex 对话终端窗口准备好后输入codex回车就进入了 Codex 的交互式对话模式。这时你直接打字提需求比如“帮我写一个 Python 脚本读取当前目录下所有 md 文件并统计字数”Codex 就会自己规划、生成命令并执行。整个会话过程都留在 Obsidian 的终端面板里和旁边的笔记内容对照着看效率很高。如果你想退出对话输入exit或按CtrlC两次即可。这个终端面板是 Obsidian 的一个普通标签页可以拖到右侧栏也可以和笔记分屏显示。我习惯把它放在右侧宽度设为 400px 左右既不挡笔记正文又能随叫随到。3.5 把对话输出保存成笔记的两种方式终端里的对话默认不会自动写进笔记但 Obsidian 的价值在于积累所以我一般会做两层保存简单的做法选中终端里的输出直接复制粘贴到当前笔记的底部再用 Markdown 的 引用格式包一层表示这是 AI 回复。自动化的做法用 PowerShell 的管道把输出重定向到文件。比如codex exec write a bash script to backup files | Tee-Object -FilePath D:\notes\codex-output.mdTee-Object会把命令输出同时显示在终端和写入文件。把codex exec换成codex不行因为交互模式没有直接管道输出所以推荐用codex exec来跑明确的任务再用文件保存实现接近“无感记录”的效果。3.6 方案 A 的使用边界方案 A 虽然灵活但有两点要注意。第一终端里的 Codex 可以读写本地文件这意味着它能直接操作 Obsidian 的.md文件这既是优点也是风险。建议只让 Codex 操作你指定的目录比如先cd到项目文件夹再开始对话避免误改笔记库里的其他文件。第二终端插件和 Obsidian 的快捷键偶尔会冲突比如CtrlC在某些版本里会被终端插件拦截。遇到这种情况到插件设置里重新绑定终端相关快捷键或者直接用命令面板操作问题不大。4. 方案 B用 Copilot 插件直接接模型如果你不习惯终端更喜欢在笔记里选中一段文字直接让 AI 回答那方案 B 更合适。这个方案的思路是在 Obsidian 里装一个聊天插件把 Codex 对应的模型接口配置进去之后在侧边栏里就能直接对话。4.1 为什么选 Copilot for ObsidianObsidian 社区有不少 AI 聊天插件我最常用的是“Copilot for Obsidian”。它支持 OpenAI 兼容接口能在侧边栏渲染聊天界面还允许你把当前选中的笔记内容作为上下文发送给模型。这意味着你可以一边写笔记一边选中某段技术思路问 Codex“帮我检查这个思路有没有问题”它会基于选中的文本来回答答案和笔记上下文高度相关。4.2 安装并打开 Copilot安装方式与 Terminal 插件一样设置 → 第三方插件 → 浏览 → 搜索“Copilot”找到作者为 logancyang 的插件安装并启用。启用后左侧边栏会出现一个聊天图标点击即可展开聊天窗口。首次打开时插件会引导你选择聊天模型提供商。这里不要选内置的某些云服务要选“OpenAI”或者“Custom Model”相关选项因为我们要自己填端点。4.3 配置自定义 OpenAI 兼容端点打开 Copilot 设置找到“Chat models”相关区域。关键字段如下配置项填写内容备注ProviderOpenAI或者选择“Custom”后手动填Base URLhttps://api.openai.com/v1有些版本会要求填到/v1/chat/completions如果出现 404去掉后面的路径再试API Keysk-...你的密钥Model ID以你官方控制台实际可用的 Codex 模型名为准可先填一个常见 ID 测试比如gpt-5-codex填完后点击“Test”或直接发一条消息测试。如果插件提示“model not supported”问题基本出在 Model ID 上。不要看到网上有人填gpt-5.6-sol就照抄那可能是某个私人网关的自定义模型名官方 API 根本不认识。正确做法是去 OpenAI 官方的模型列表页找到你账号有权访问的那个 Codex 系列模型 ID填进来。4.4 选中笔记内容直接对话配置成功后使用方式就非常顺滑了。在 Obsidian 里打开一篇笔记用鼠标选中你想要讨论的段落然后调出 Copilot 面板输入你的问题比如“请把这段文字转换成更口语化的表达”插件会把选中的文字带入上下文返回的结果直接显示在侧边栏里。如果想让 Codex 针对整篇笔记进行总结可以不用选区直接输入“总结这篇笔记的要点”。不过要注意默认情况下 Copilot 只发送当前笔记的内容不一定包含整个 Vault 的其他文件这是合理的隐私设计也方便控制 token 消耗。4.5 方案 B 的局限与应对方案 B 的代价是它走的是标准模型 API不能像方案 A 那样让 Codex 直接在本地执行代码和读写文件。如果你只是想要对话补全、代码片段建议、文本润色这个方案完全够用但如果你是希望 AI 帮你跑通项目、运行命令、排查日志那还是回到方案 A。还有一个常见问题是 API 请求报 401 或者 403。401 基本是 API Key 填错或密钥失效重新创建一个密钥再更新即可。403 多是因为当前账号没有权限访问某些模型这种情况要么换一个当前账号能用的模型 ID要么确认你需要开通对应的付费计划插件本身没有快捷解法。5. 常见报错与避坑经验配置过程中不可避免地会遇到各种问题这里把我实际踩过的、以及社区里高频出现的问题汇总一下按场景拆开讲。5.1 Obsidian 下载慢、插件市场打不开这一步几乎是每个 Windows 新手都会卡住的地方。Obsidian 的社区插件市场默认直连 GitHub 和官方源网络波动时经常加载不出列表甚至连主程序安装包都下载失败。我的建议是主程序优先用微软商店版本插件则尝试多刷新几次或者换一个网络环境再打开。如果插件市场实在打不开可以手动安装插件前往该插件的 GitHub Releases 页面下载对应版本的 zip 包解压到 Obsidian 安装目录下的Vault/.obsidian/plugins/插件名文件夹里然后重启 Obsidian 并在第三方插件列表里手动启用。手动安装的插件和官方市场安装的效果完全一样只是少了“一键更新”的便利。5.2codex命令不是内部或外部命令安装 npm 包后如果执行codex时报“不是内部或外部命令”九成是 npm 全局目录不在系统 PATH 里。Windows 上 npm 默认的全局安装路径是C:\Users\你的用户名\AppData\Roaming\npm。你需要把这个路径加入环境变量 PATH。操作步骤还是设置 → 系统 → 关于 → 高级系统设置 → 环境变量 → 编辑用户变量里的Path→ 新建 → 粘贴上面的路径。保存后务必重新打开一个终端窗口再执行codex --version。如果你实在不想改系统变量也可以每次用npx openai/codex来运行效果一样但每次启动会稍慢一点不推荐长期使用。5.3 对话时报网络链路错误Codex CLI 在连接模型服务时如果本地网络无法直接访问 API会报出一段冗长的错误。比如有时会出现类似cc switch ... failed while handling codex endpoint /responses的信息。看到这种错误先不要怀疑 Codex 配置而是检查网络连通性。你可以在终端里跑curl https://api.openai.com/v1/models -H Authorization: Bearer $env:OPENAI_API_KEY如果能返回 JSON说明网络是通的问题更可能出现在 Codex 自身的认证或模型配置上。如果这条命令也卡住或超时那就是网络链路本身无法直连该域名你需要从系统网络设置、防火墙规则、DNS 解析这些基础项入手排查而不是继续折腾 Codex 的配置文件。5.4 模型不支持报错另一个高频错误是类似the gpt-5.6-sol model is not supported when using codex with a ...。这种报错的本质是你填写的模型 ID 和当前认证方式不匹配或者这个模型 ID 根本不存在于 Codex 支持列表中。解决办法分两步第一步打开%USERPROFILE%\.codex\config.toml检查model字段把它改回官方默认值或明确可用的模型 ID第二步如果用了第三方网关或自定义模型名先切回官方 API 测试一下确认基础功能正常后再逐项加自定义配置。我的经验是新手阶段不要追求“最新模型名”能用、稳定、文档明确支持的模型才是最高效的。5.5 对话内容太乱、记录散落各处这不是报错但比报错更消磨耐心。Codex CLI 的交互式会话默认不写入 Obsidian 笔记会话记录保存在用户目录.codex下的 session 文件里。如果你希望有一条清晰的时间线最稳妥的做法是固定一个“Codex 对话收集箱”笔记每次把有价值的输出手动粘贴进去并打上#codex标签。后面用 Obsidian 自带的搜索或 Dataview 插件就能按标签聚合所有 AI 对话。6. 把 AI 对话变成笔记资产我的几个进阶习惯配置跑通只是开始。用了一段时间后我发现真正让这套组合发挥价值的是如何把零散的 AI 对话沉淀成可复用的笔记资产。这里分享三个不会增加太多操作成本的习惯。6.1 用模板一键建立对话记录我写了一个 Obsidian 模板专门用来记录 Codex 对话。模板内容大致是--- type: codex-session tags: [codex, AI] date: {{date}} --- # Codex 对话记录 ## 背景 写下这次想解决的问题 ## 问题 一句话描述需求 ## Codex 方案 粘贴关键输出 ## 我的验证结果 是否可用、修改了什么配合 Templater 插件每次要做 AI 对话前我先用模板新建一篇笔记再打开终端或 Copilot 开始问。这样对话有背景、有结论、有验证记录一个月后回看还是很清楚。6.2 给代码块做标记保持 Obsidian 渲染正常Codex 经常输出多语言代码块。复制进笔记时注意一定要保留 Markdown 代码块语法比如python。如果直接粘贴纯文本Obsidian 里不会高亮也会破坏笔记结构。这个小细节看着不起眼但对后续阅读体验影响很大。对于特别满意的回复我还会在代码块下方加一条“为什么可用”的注释把判断依据写下来。这比单纯存档 AI 回复更有价值因为你把“验证过的知识”存了下来而不是存了一段不知道能不能跑的话。6.3 把敏感信息挡在对话之外最后一条是安全底线。无论是方案 A 还是方案 BAI 对话本质上会把内容发送到模型服务端所以绝对不要把 API Key、密码、个人身份证号、公司内部机密直接贴进对话。我见过有人为了图方便把环境变量文件内容一整个发给 Codex让它帮忙改配置这是非常大的泄露风险。我的建议是在 Obsidian 里设定一个“敏感信息禁区”文件夹凡是包含密钥或隐私的笔记不要放到 AI 对话的上下文中同时在 Copilot 插件设置里关闭“发送当前文件全文作为上下文”这类开关改用选区发送尽可能减少暴露面。6.4 善用 Obsidian 的分屏和快捷键如果方案 A 是你的主力强烈建议把终端面板固定在右侧栏并记住两个快捷键CtrlP打开命令面板输入“Terminal: Open new terminal”启动终端CtrlT切换新标签页。熟练之后整个操作流是按下CtrlP→ 输入 term → 回车 → 瞬间出现终端 → 敲codex→ 开始对话。全过程不超过五秒比切到外部终端再切回来利落得多。我个人实际用下来方案 A 和方案 B 不是二选一的关系。方案 A 适合让 Codex 动手做事比如写脚本、分析文件、跑测试方案 B 适合让它当“对话搭子”随时回答问题、润色文本。两个都配好之后Obsidian 就不再只是静态的笔记仓库而是一个随时有 AI 在旁边配合的工作台。最后再分享一个小技巧在 Obsidian 的命令面板里把“Terminal: Open new terminal”绑定到一个顺手的热键比如CtrlEnter用起来会顺手很多。希望这份 Windows 配置教程能帮你少走几步弯路早日把这个组合真正用起来。