我是怎么把 Obsidian 接上 AI 的：Copilot、Codeian 和 Codex 配置避坑

在 Obsidian 中接入 AI：Copilot、Codeian 和 Codex 配置指南

最近我折腾了一下 Obsidian 的 AI 插件，主要想实现两件事：

这篇就当是一份配置记录，供有类似需求的朋友参考。

先说结论：你可能需要两个插件

如果你只是想在 Obsidian 里总结笔记、问问题、做语义搜索，优先装 Copilot。

如果你想在 Obsidian 里调用本机 Codex CLI，让它像一个本地助手一样读写你的笔记库，那就装 Codeian。

简单对比一下：

一句话：

• 笔记问答，用 Copilot。
• 想让 AI 帮你整理、修改 vault 文件，用 Codeian + Codex CLI。

整体流程大概是这样：

#mermaid-svg-oWNqrixuifLuMxom{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-oWNqrixuifLuMxom .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-oWNqrixuifLuMxom .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-oWNqrixuifLuMxom .error-icon{fill:#552222;}#mermaid-svg-oWNqrixuifLuMxom .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-oWNqrixuifLuMxom .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-oWNqrixuifLuMxom .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-oWNqrixuifLuMxom .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-oWNqrixuifLuMxom .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-oWNqrixuifLuMxom .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-oWNqrixuifLuMxom .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-oWNqrixuifLuMxom .marker{fill:#333333;stroke:#333333;}#mermaid-svg-oWNqrixuifLuMxom .marker.cross{stroke:#333333;}#mermaid-svg-oWNqrixuifLuMxom svg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-oWNqrixuifLuMxom p{margin:0;}#mermaid-svg-oWNqrixuifLuMxom .label{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;color:#333;}#mermaid-svg-oWNqrixuifLuMxom .cluster-label text{fill:#333;}#mermaid-svg-oWNqrixuifLuMxom .cluster-label span{color:#333;}#mermaid-svg-oWNqrixuifLuMxom .cluster-label span p{background-color:transparent;}#mermaid-svg-oWNqrixuifLuMxom .label text,#mermaid-svg-oWNqrixuifLuMxom span{fill:#333;color:#333;}#mermaid-svg-oWNqrixuifLuMxom .node rect,#mermaid-svg-oWNqrixuifLuMxom .node circle,#mermaid-svg-oWNqrixuifLuMxom .node ellipse,#mermaid-svg-oWNqrixuifLuMxom .node polygon,#mermaid-svg-oWNqrixuifLuMxom .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-oWNqrixuifLuMxom .rough-node .label text,#mermaid-svg-oWNqrixuifLuMxom .node .label text,#mermaid-svg-oWNqrixuifLuMxom .image-shape .label,#mermaid-svg-oWNqrixuifLuMxom .icon-shape .label{text-anchor:middle;}#mermaid-svg-oWNqrixuifLuMxom .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-oWNqrixuifLuMxom .rough-node .label,#mermaid-svg-oWNqrixuifLuMxom .node .label,#mermaid-svg-oWNqrixuifLuMxom .image-shape .label,#mermaid-svg-oWNqrixuifLuMxom .icon-shape .label{text-align:center;}#mermaid-svg-oWNqrixuifLuMxom .node.clickable{cursor:pointer;}#mermaid-svg-oWNqrixuifLuMxom .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-oWNqrixuifLuMxom .arrowheadPath{fill:#333333;}#mermaid-svg-oWNqrixuifLuMxom .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-oWNqrixuifLuMxom .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-oWNqrixuifLuMxom .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-oWNqrixuifLuMxom .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-oWNqrixuifLuMxom .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-oWNqrixuifLuMxom .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-oWNqrixuifLuMxom .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-oWNqrixuifLuMxom .cluster text{fill:#333;}#mermaid-svg-oWNqrixuifLuMxom .cluster span{color:#333;}#mermaid-svg-oWNqrixuifLuMxom div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-oWNqrixuifLuMxom .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-oWNqrixuifLuMxom rect.text{fill:none;stroke-width:0;}#mermaid-svg-oWNqrixuifLuMxom .icon-shape,#mermaid-svg-oWNqrixuifLuMxom .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-oWNqrixuifLuMxom .icon-shape p,#mermaid-svg-oWNqrixuifLuMxom .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-oWNqrixuifLuMxom .icon-shape .label rect,#mermaid-svg-oWNqrixuifLuMxom .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-oWNqrixuifLuMxom .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-oWNqrixuifLuMxom .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-oWNqrixuifLuMxom :root{–mermaid-font-family:\”trebuchet ms\”,verdana,arial,sans-serif;}

安装 Obsidian

打开自己的 Vault

开启社区插件

安装 Copilot

填 API Key 并验证

安装 Codeian

检查 Codex CLI

开始使用

1. 先安装 Obsidian

官网下载地址：

https://obsidian.md/download

macOS 一般下载 .dmg 文件。下载后正常安装就行：

如果 macOS 提示安全拦截，不用慌。去这里放行：

系统设置 -> 隐私与安全性

找到 Obsidian，点"仍要打开"。

2. 打开你真正要用的 Vault

Obsidian 的插件是跟着 vault 走的。

也就是说，你在 A 笔记库里装了插件，B 笔记库不一定有。所以别在示例库里折腾半天，最后发现自己真正写东西的库里啥也没有。

新建 vault：

打开已有笔记目录：

建议：直接在你日常使用的 vault 里配置 AI 插件。

3. 打开社区插件开关

Obsidian 默认会限制社区插件，所以要先关掉受限模式。

英文界面路径：

Settings -> Community plugins -> Restricted mode -> Turn off

中文界面大概是：

设置 -> 第三方插件 / 社区插件 -> 关闭受限模式

然后点：

Browse

就可以搜索插件了。

4. 先配置 Copilot：用来问笔记、总结笔记

Copilot 是最适合先装的那个。它可以做笔记问答、总结、语义检索，日常使用频率会比较高。

安装 Copilot

步骤很简单：

填 API Key

进入：

Settings -> Copilot

找到：

AI Provider Settings

选择国内合规的 AI 服务提供商（如阿里云百炼、百度千帆、智谱 AI、火山引擎等），填写对应的 API Key，然后点：

Verify

模型可以先这样选（以阿里云百炼为例）：

Chat Model: qwen-turbo 或 qwen-plus
Embedding Model: text-embedding-v2

如果插件里有"刷新模型列表"之类的按钮，可以先点一下，再选模型。

API Key 去哪里拿

以阿里云百炼为例：

https://bailian.console.aliyun.com/

几个提醒：

• API Key 是单独计费的，与网页版会员不通用。
• API Key 不要写进普通笔记。
• 截图时不要露出完整 key。

可以把 API Key 理解成"API 钱包钥匙"。别人拿到它，就可能花你的额度。

5. Copilot 报错时，看这几个关键词

AI 插件的报错经常一大段，看着吓人。其实先抓关键词就行。

报 API_KEY_INVALID

你可能会看到类似：

API key verification failed
API_KEY_INVALID
API key not valid

处理方式：

报 invalid_api_key

如果看到：

invalid_api_key
Incorrect API key provided

说明服务已经收到请求了，但 key 是错的。

处理方式：

报 fetch failed 或连接超时

如果看到：

fetch failed
ConnectTimeoutError
connection timeout

这通常不是 key 的问题，而是网络连接问题。

处理方式：

6. 网络连接问题排查

如果 API 服务连不上，可以按这个顺序排查：

7. 再配置 Codeian：把 Codex 接进 Obsidian

Copilot 是"问笔记"的。

Codeian 更像是"在 Obsidian 里打开一个 Codex 侧边栏"。它会调用你本机已经装好的 Codex CLI。

所以配 Codeian 之前，先确认本机 Codex CLI 是好的。

检查 Codex CLI

打开终端，执行：

codex –version

如果能看到版本号，说明装好了。

再检查登录状态：

codex login status

如果显示已登录，就可以继续。

安装 Codeian

优先用 Obsidian 社区插件安装：

如果搜不到，也可以手动安装：

.obsidian/plugins/codeian/

8. Codeian 怎么填配置

进入：

Settings -> Codeian

推荐这样填：

CLI command: /usr/local/bin/codex
Codex arguments: –ask-for-approval never exec –skip-git-repo-check
File access: Write / workspace-write
Working directory: $VAULT_PATH
Default model: 留空或使用默认
Default effort: medium

这里的 $VAULT_PATH 换成你的 vault 路径，比如：

/Users/your-name/Documents/my-vault

几个地方解释一下：

• CLI command 最好写完整路径，比如 /usr/local/bin/codex，这样 Obsidian 不容易找错。
• workspace-write 表示允许 Codex 修改当前 vault 或 workspace 里的文件。
• 不建议选 YOLO 或 danger-full-access，这个权限太大。
• –ask-for-approval never 是为了让 Codex 在 Obsidian 里能跑起来，不然它可能一直等你在命令行里确认。

这里要稍微谨慎一点。我的建议是：先用 workspace-write，不要一上来就给全盘权限。

Codeian 的关系可以理解成：

#mermaid-svg-ukL86exfYGHUYbIG{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;fill:#333;}@keyframes edge-animation-frame{from{stroke-dashoffset:0;}}@keyframes dash{to{stroke-dashoffset:0;}}#mermaid-svg-ukL86exfYGHUYbIG .edge-animation-slow{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 50s linear infinite;stroke-linecap:round;}#mermaid-svg-ukL86exfYGHUYbIG .edge-animation-fast{stroke-dasharray:9,5!important;stroke-dashoffset:900;animation:dash 20s linear infinite;stroke-linecap:round;}#mermaid-svg-ukL86exfYGHUYbIG .error-icon{fill:#552222;}#mermaid-svg-ukL86exfYGHUYbIG .error-text{fill:#552222;stroke:#552222;}#mermaid-svg-ukL86exfYGHUYbIG .edge-thickness-normal{stroke-width:1px;}#mermaid-svg-ukL86exfYGHUYbIG .edge-thickness-thick{stroke-width:3.5px;}#mermaid-svg-ukL86exfYGHUYbIG .edge-pattern-solid{stroke-dasharray:0;}#mermaid-svg-ukL86exfYGHUYbIG .edge-thickness-invisible{stroke-width:0;fill:none;}#mermaid-svg-ukL86exfYGHUYbIG .edge-pattern-dashed{stroke-dasharray:3;}#mermaid-svg-ukL86exfYGHUYbIG .edge-pattern-dotted{stroke-dasharray:2;}#mermaid-svg-ukL86exfYGHUYbIG .marker{fill:#333333;stroke:#333333;}#mermaid-svg-ukL86exfYGHUYbIG .marker.cross{stroke:#333333;}#mermaid-svg-ukL86exfYGHUYbIG svg{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:16px;}#mermaid-svg-ukL86exfYGHUYbIG p{margin:0;}#mermaid-svg-ukL86exfYGHUYbIG .label{font-family:\”trebuchet ms\”,verdana,arial,sans-serif;color:#333;}#mermaid-svg-ukL86exfYGHUYbIG .cluster-label text{fill:#333;}#mermaid-svg-ukL86exfYGHUYbIG .cluster-label span{color:#333;}#mermaid-svg-ukL86exfYGHUYbIG .cluster-label span p{background-color:transparent;}#mermaid-svg-ukL86exfYGHUYbIG .label text,#mermaid-svg-ukL86exfYGHUYbIG span{fill:#333;color:#333;}#mermaid-svg-ukL86exfYGHUYbIG .node rect,#mermaid-svg-ukL86exfYGHUYbIG .node circle,#mermaid-svg-ukL86exfYGHUYbIG .node ellipse,#mermaid-svg-ukL86exfYGHUYbIG .node polygon,#mermaid-svg-ukL86exfYGHUYbIG .node path{fill:#ECECFF;stroke:#9370DB;stroke-width:1px;}#mermaid-svg-ukL86exfYGHUYbIG .rough-node .label text,#mermaid-svg-ukL86exfYGHUYbIG .node .label text,#mermaid-svg-ukL86exfYGHUYbIG .image-shape .label,#mermaid-svg-ukL86exfYGHUYbIG .icon-shape .label{text-anchor:middle;}#mermaid-svg-ukL86exfYGHUYbIG .node .katex path{fill:#000;stroke:#000;stroke-width:1px;}#mermaid-svg-ukL86exfYGHUYbIG .rough-node .label,#mermaid-svg-ukL86exfYGHUYbIG .node .label,#mermaid-svg-ukL86exfYGHUYbIG .image-shape .label,#mermaid-svg-ukL86exfYGHUYbIG .icon-shape .label{text-align:center;}#mermaid-svg-ukL86exfYGHUYbIG .node.clickable{cursor:pointer;}#mermaid-svg-ukL86exfYGHUYbIG .root .anchor path{fill:#333333!important;stroke-width:0;stroke:#333333;}#mermaid-svg-ukL86exfYGHUYbIG .arrowheadPath{fill:#333333;}#mermaid-svg-ukL86exfYGHUYbIG .edgePath .path{stroke:#333333;stroke-width:2.0px;}#mermaid-svg-ukL86exfYGHUYbIG .flowchart-link{stroke:#333333;fill:none;}#mermaid-svg-ukL86exfYGHUYbIG .edgeLabel{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-ukL86exfYGHUYbIG .edgeLabel p{background-color:rgba(232,232,232, 0.8);}#mermaid-svg-ukL86exfYGHUYbIG .edgeLabel rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-ukL86exfYGHUYbIG .labelBkg{background-color:rgba(232, 232, 232, 0.5);}#mermaid-svg-ukL86exfYGHUYbIG .cluster rect{fill:#ffffde;stroke:#aaaa33;stroke-width:1px;}#mermaid-svg-ukL86exfYGHUYbIG .cluster text{fill:#333;}#mermaid-svg-ukL86exfYGHUYbIG .cluster span{color:#333;}#mermaid-svg-ukL86exfYGHUYbIG div.mermaidTooltip{position:absolute;text-align:center;max-width:200px;padding:2px;font-family:\”trebuchet ms\”,verdana,arial,sans-serif;font-size:12px;background:hsl(80, 100%, 96.2745098039%);border:1px solid #aaaa33;border-radius:2px;pointer-events:none;z-index:100;}#mermaid-svg-ukL86exfYGHUYbIG .flowchartTitleText{text-anchor:middle;font-size:18px;fill:#333;}#mermaid-svg-ukL86exfYGHUYbIG rect.text{fill:none;stroke-width:0;}#mermaid-svg-ukL86exfYGHUYbIG .icon-shape,#mermaid-svg-ukL86exfYGHUYbIG .image-shape{background-color:rgba(232,232,232, 0.8);text-align:center;}#mermaid-svg-ukL86exfYGHUYbIG .icon-shape p,#mermaid-svg-ukL86exfYGHUYbIG .image-shape p{background-color:rgba(232,232,232, 0.8);padding:2px;}#mermaid-svg-ukL86exfYGHUYbIG .icon-shape .label rect,#mermaid-svg-ukL86exfYGHUYbIG .image-shape .label rect{opacity:0.5;background-color:rgba(232,232,232, 0.8);fill:rgba(232,232,232, 0.8);}#mermaid-svg-ukL86exfYGHUYbIG .label-icon{display:inline-block;height:1em;overflow:visible;vertical-align:-0.125em;}#mermaid-svg-ukL86exfYGHUYbIG .node .label-icon path{fill:currentColor;stroke:revert;stroke-width:revert;}#mermaid-svg-ukL86exfYGHUYbIG :root{–mermaid-font-family:\”trebuchet ms\”,verdana,arial,sans-serif;}

Obsidian Vault

Codeian 插件

本机 Codex CLI

当前 Vault 工作目录

读取或修改 Markdown 文件

9. 配完 Codeian 后，先做一个小测试

重启 Obsidian 后，先看三个地方：

然后在 Codeian 侧边栏里输入：

请只回复 OK

如果它返回：

OK

说明 Codeian 到 Codex CLI 这条路已经通了。

再做一个只读测试：

请总结当前笔记的主要内容，不要修改文件。

如果它能总结当前笔记，说明它已经能读到你的笔记上下文。

10. 日常怎么用

Copilot 更适合这种问题：

总结当前笔记
根据我的 vault 回答某个问题
帮我找与某个主题相关的笔记
把这段内容整理成待办清单

Codeian 更适合这种任务：

检查这个 vault 中某个主题的文档结构，并给出改进建议
帮我把当前笔记整理成 PRD 格式
在不删除原内容的前提下，追加一份测试用例清单
检查这个目录下 Markdown 文件是否有重复标题

如果你只是想让它看一看，不想让它改文件，可以直接写清楚：

只读分析，不要改文件。

如果你想更稳一点，可以这样说：

请先说明你要修改哪些文件，等我确认后再修改。

出问题时，按这个顺序查

别一上来就重装插件。大部分问题不是插件坏了，而是 key、网络、路径这些地方没配对。

建议按这个顺序排查：

常见情况可以这么判断：

最后说一下安全问题

这块别嫌麻烦，真挺重要。

• API Key 只填在插件设置里，不要写进普通笔记。
• 不要把带完整 key 的截图发到公开地方。
• Codeian 不要轻易使用 danger-full-access。
• 重要 vault 最好用 Git 或其他方式备份。
• 让 AI 修改文件前，最好要求它先说明修改范围。
• 插件升级前，可以先备份配置文件：

.obsidian/plugins/<plugin-name>/data.json

最小可用清单

如果你只想快速跑通，对照这两张清单就行。

Copilot

[ ] 插件已启用
[ ] 国内合规 AI 服务 API Key 有效
[ ] Chat Model 可用
[ ] Embedding Model 可用
[ ] 网络能正常访问所选服务商 API

Codeian

[ ] 插件已启用
[ ] Codex CLI 已安装
[ ] Codex CLI 已登录
[ ] CLI command 指向 codex 绝对路径
[ ] Working directory 指向当前 vault
[ ] Sandbox 使用 workspace-write

做到这里，Obsidian 的 AI 能力基本就能稳定用了。后面要不要继续细调模型、提示词、索引范围，就看你自己的使用习惯了。