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

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

1. 在 Obsidian 里直接问笔记、总结笔记。
2. 把本机的 Codex 接进 Obsidian，让它能在笔记库里帮我干活。

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

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

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

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

简单对比一下：

工具	它是干嘛的	你需要准备什么
Copilot	在 Obsidian 里聊天、总结、问笔记	国内合规 AI 服务 API Key（如阿里云百炼、百度千帆、智谱 AI 等）
Codeian	在 Obsidian 侧边栏里跑 Codex	本机已经装好并登录 Codex CLI
Codex CLI	命令行里的 AI 助手	Codex CLI 登录状态正常

一句话：

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

整体流程大概是这样：

1. 先安装 Obsidian

官网下载地址：

https://obsidian.md/download

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

1. 双击 .dmg
2. 把 Obsidian.app 拖到 Applications / 应用程序
3. 打开 Obsidian

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

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

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

2. 打开你真正要用的 Vault

Obsidian 的插件是跟着 vault 走的。

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

新建 vault：

1. 打开 Obsidian
2. 选择 Create new vault
3. 填名称
4. 选本地目录
5. 创建

打开已有笔记目录：

1. 点击左下角 vault 名称
2. 选择 Open another vault
3. 选择 Open folder as vault
4. 选中你的笔记目录

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

3. 打开社区插件开关

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

英文界面路径：

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

中文界面大概是：

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

然后点：

Browse

就可以搜索插件了。

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

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

安装 Copilot

步骤很简单：

1. 打开 Settings
2. 进入 Community plugins
3. 点击 Browse
4. 搜索 Copilot
5. 点击 Install
6. 安装完成后点 Enable

填 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

处理方式：

1. 进入 Settings -> Copilot
2. 打开 AI Provider Settings
3. 检查 API Key 是否填写正确
4. 确认使用的是国内合规服务商的 key
5. 重新选择模型
6. 保存配置

报 invalid_api_key

如果看到：

invalid_api_key
Incorrect API key provided

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

处理方式：

1. 删除旧 key
2. 去对应平台重新创建 key
3. 粘贴新 key
4. 再点 Verify

报 fetch failed 或连接超时

如果看到：

fetch failed
ConnectTimeoutError
connection timeout

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

处理方式：

1. 检查网络连接是否正常。
2. 确认所选服务商的 API 地址是否可访问。
3. 重启 Obsidian，再点一次 Verify。

6. 网络连接问题排查

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

1. 检查本地网络连接是否正常。
2. 确认所选 AI 服务商的 API 端点地址是否正确。
3. 重启 Obsidian。
4. 回到 Copilot 重新点 Verify。

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

Copilot 是"问笔记"的。

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

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

检查 Codex CLI

打开终端，执行：

codex --version

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

再检查登录状态：

codex login status

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

安装 Codeian

优先用 Obsidian 社区插件安装：

1. 打开 Settings
2. 进入 Community plugins
3. 点击 Browse
4. 搜索 Codeian
5. 点击 Install
6. 点击 Enable

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

1. 打开 Codeian 的 GitHub release 页面
2. 下载 main.js
3. 下载 manifest.json
4. 下载 styles.css
5. 在 vault 中创建目录：

.obsidian/plugins/codeian/

6. 把三个文件放进去
7. 重启 Obsidian
8. 回到社区插件列表启用 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 的关系可以理解成：

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

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

1. 左侧 ribbon 有没有 Codeian / 机器人图标。
2. 命令面板里能不能搜到 Codeian。
3. Settings -> Community plugins 里 Codeian 是否已启用。

然后在 Codeian 侧边栏里输入：

请只回复 OK

如果它返回：

OK

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

再做一个只读测试：

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

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

10. 日常怎么用

Copilot 更适合这种问题：

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

Codeian 更适合这种任务：

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

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

只读分析，不要改文件。

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

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

出问题时，按这个顺序查

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

建议按这个顺序排查：

1. 插件有没有启用。
2. API Key 有没有填对。
3. 网络连接是否正常。
4. 模型名有没有选错。
5. vault 路径是不是当前正在用的那个。
6. Codex CLI 有没有安装并登录。
7. Obsidian 有没有重启。

常见情况可以这么判断：

现象	大概率原因	怎么办
invalid_api_key	API Key 无效	重新创建 key
fetch failed / 超时	网络不通	检查网络连接
Codeian 不启动	CLI 路径或登录状态异常	检查 codex --version 和 codex login status

最后说一下安全问题

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

• 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 能力基本就能稳定用了。后面要不要继续细调模型、提示词、索引范围，就看你自己的使用习惯了。