OpenCode + Obsidian：打造你的AI驱动知识管理工作流

Thu, 30 Apr 2026 02:00:15 +0800

📋 目录

一、什么是 opencode-obsidian 插件？

opencode-obsidian 是一个第三方社区插件，它将 OpenCode AI 助手直接嵌入到 Obsidian 窗口中。不同于传统的终端集成方案，这个插件使用 OpenCode 的 Web 视图直接嵌入，你看到的就是完整的 OpenCode 界面，不需要在终端和 Obsidian 之间来回切换。

核心特性：

🖥️ OpenCode 界面直接嵌入 Obsidian 侧边栏或主编辑区
🔄 服务端自动管理——打开面板即启动，关闭即停止
📄 实验性的上下文注入——自动将当前打开的笔记和选中文本传给 AI
⌨️ 快捷键 Ctrl/Cmd + Shift + O 快速切换面板

适用场景：

总结和提炼长文本内容
起草、编辑和润色写作
查询和探索你的知识库
生成大纲和结构化笔记

⚠️ 插件作者与 OpenCode / Obsidian 无关联，这是一个独立的第三方项目。目前版本为 0.2.1（Beta 阶段），仅支持桌面端。

二、环境准备

在开始之前，确保你已准备好以下内容：

项目	要求	说明
Obsidian	≥ 1.4.0	官网下载
Node.js	≥ 18+	下载地址，用于安装 OpenCode

准备就绪后，跟着下面的步骤走就行。

三、安装 BRAT 插件

BRAT（Beta Reviewer’s Auto-update Tool）是 Obsidian 的一个社区插件，专门用来安装尚未上架社区插件市场的 Beta 版插件。opencode-obsidian 目前还没有正式上架，所以需要通过 BRAT 安装。

步骤 1：打开社区插件市场

在 Obsidian 中依次点击：设置 → 第三方插件 → 关闭「安全模式」→ 社区插件市场

步骤 2：搜索并安装 BRAT

在社区插件市场中搜索 BRAT（全名：Obsidian42 - BRAT），点击「安装」→「启用」。

💡 BRAT 的全称是 Beta Reviewer’s Auto-update Tool，由 TfTHacker 开发。它能自动检测 Beta 插件的更新并提醒你升级。

四、通过 BRAT 安装 opencode-obsidian

安装好 BRAT 后，就可以用它来安装 opencode-obsidian 插件了。

步骤 1：打开 BRAT 设置

设置 → 第三方插件 → 找到已安装的 BRAT，点击右侧的齿轮图标进入设置。

步骤 2：添加 Beta 插件

在 BRAT 设置页面中，点击 「Add Beta plugin」 按钮。

步骤 3：输入仓库地址

在弹出的输入框中输入：

`1`	`mtymek/opencode-obsidian`

点击 「Add Plugin」。

BRAT 会自动从 GitHub 拉取最新的 release 版本并安装。

步骤 4：启用插件

安装完成后，前往设置 → 第三方插件 → 在「已安装插件」列表中找到 OpenCode-Obsidian，打开开关启用它。

✅ 启用后，Obsidian 左侧栏会出现一个终端样式的图标——这就是 OpenCode 的入口。

自动更新

BRAT 会定期检查 GitHub 上的新版本。当有更新时，它会在 Obsidian 中弹出通知，你只需点击确认即可自动升级。

五、安装 OpenCode CLI

插件本身只是一个"壳"——它会在后台启动 opencode serve 服务，然后把 OpenCode 的 Web 界面嵌入到 Obsidian 里。所以你只需要通过 npm 安装 OpenCode CLI 就够了。

打开系统的终端（Windows 用 PowerShell，macOS/Linux 用 Terminal）：

`1`	`npm i -g opencode-ai`

验证安装：

1
2

opencode --version
# 期望输出类似: 1.14.39

⚠️ Windows 用户：如果插件提示「Executable not found at ‘opencode’」，请跳到本文第十节查看解决方案。

六、插件设置详解

启用插件后，进入设置 → 第三方插件 → OpenCode-Obsidian 的齿轮图标，可以看到以下配置项：

基础设置

设置项	默认值	说明
OpenCode 可执行文件路径	`opencode`	如果系统 PATH 中找不到，填入完整路径
端口	`14096`	OpenCode 服务监听的端口号
主机名	`127.0.0.1`	服务绑定的地址
项目目录	（自动取 Vault 路径）	OpenCode 操作的工作目录
启动超时	`45000` (45秒)	等待服务启动的最大毫秒数

界面设置

设置项	默认值	说明
默认视图位置	`sidebar`	`sidebar` = 侧边栏，`main` = 主编辑区
自动启动	`关闭`	打开 Obsidian 时自动启动 OpenCode 服务

上下文注入（实验性）

设置项	默认值	说明
注入工作区上下文	`关闭`	自动将当前笔记信息传给 OpenCode
最大笔记数量	`20`	上下文中包含的最大笔记数
最大选中文本长度	`2000`	传给 AI 的选中文本字符上限

自定义命令

设置项	默认值	说明
使用自定义命令	`关闭`	启用后可自定义 OpenCode 启动命令
自定义命令	（空）	自定义的启动命令（见第九节）

七、首次使用

打开 OpenCode 面板

有三种方式打开 OpenCode：

点击侧边栏图标：点击左侧栏的终端图标
快捷键：Ctrl + Shift + O（macOS 用 Cmd + Shift + O）
命令面板：Ctrl/Cmd + P → 输入 Toggle OpenCode panel

首次启动流程

打开面板后，插件会自动执行以下操作：

检测 OpenCode 可执行文件路径
启动 OpenCode 服务（opencode serve）
在嵌入式 Web 视图中加载 OpenCode 界面

启动成功后，你会看到完整的 OpenCode 对话界面，可以直接在里面输入 prompt。

验证一切正常

在 OpenCode 界面中输入：

/help

如果看到命令列表，说明一切正常。你也可以输入：

/models

查看可用的 AI 模型。OpenCode 内置了免费模型（如 GLM-4.7、MiniMax-2.1），无需任何配置即可使用。

快捷键速查

快捷键	功能
`Ctrl/Cmd + Shift + O`	切换 OpenCode 面板

八、上下文注入（实验性功能）

这是 opencode-obsidian 插件最独特的功能之一——它可以自动将 Obsidian 的工作上下文传递给 OpenCode。

开启方式

在插件设置中，打开 「注入工作区上下文」 开关。

注入的内容

启用后，插件会自动将以下信息传给正在运行的 OpenCode 实例：

📂 当前打开的笔记列表：你正在编辑哪些文件
📝 选中的文本：你在笔记中选中的文字

使用场景

选中一段文字，打开 OpenCode 面板，直接说「润色这段话」——AI 已经知道你说的是哪段文字
同时打开多篇笔记，让 AI「对比这两篇笔记的差异」——AI 已经知道你打开的是哪些文件

局限性

⚠️ 这是实验性功能，目前有一些限制：

在 OpenCode 界面中创建新 Session 时，上下文不会自动注入

上下文更新有一定的延迟

九、自定义命令模式

默认情况下，插件会自动调用 opencode serve 命令启动服务。如果你需要更多控制，可以启用自定义命令模式。

什么时候需要自定义命令？

需要添加额外的 CLI 参数
使用自定义的启动脚本
通过容器或虚拟环境运行 OpenCode
OpenCode 安装在非标准路径

配置步骤

在插件设置中打开 「使用自定义命令」
在 「自定义命令」 输入框中填写完整命令

命令模板

`1`	`opencode serve --port 14096 --hostname 127.0.0.1 --cors app://obsidian.md`

⚠️ 重要注意事项

端口和主机名必须与设置中的值一致
必须包含 --cors app://obsidian.md，否则 Obsidian 无法嵌入 OpenCode 的 Web 界面

十、常见问题与故障排除

❌ 找不到 OpenCode 可执行文件

现象：打开面板后提示「Executable not found at ‘opencode’」，但终端中执行 opencode 是正常的。

原因：Electron（Obsidian 底层框架）在 Windows 上不完全继承系统 PATH 环境变量。

解决方案：

在终端中查找 opencode.cmd 的完整路径：

`1`	`where opencode.cmd`

将输出的完整路径填入插件设置的「OpenCode 可执行文件路径」中，例如：

`1`	`C:\Users\你的用户名\AppData\Roaming\npm\opencode.cmd`

❌ 服务启动超时

可能原因：网络问题、模型加载慢、端口被占用。

解决方案：

检查端口 14096 是否被其他程序占用
尝试修改端口号（比如改成 15096）
增加启动超时时间

❌ 面板显示空白

可能原因：CORS 配置不正确。

解决方案：

如果使用了自定义命令，确保命令中包含 --cors app://obsidian.md。

❌ 面板无法嵌入

可能原因：OpenCode 版本过旧。

解决方案：

`1`	`npm i -g opencode-ai@latest`

❌ 中文文件名乱码（Windows）

解决方案：在 PowerShell 中执行：

`1`	`chcp 65001`

然后重启 Obsidian。

❌ 插件更新后需要重新配置

BRAT 更新插件时会保留你的设置数据。如果发现设置丢失，重新进入设置页面配置即可。

总结

整个安装流程可以用一张图概括：

┌──────────────────────────────────────────┐
│           安装 BRAT 插件                  │
│   设置 → 社区插件市场 → 搜索 BRAT → 安装   │
└──────────────────┬───────────────────────┘
                   │
                   ▼
┌──────────────────────────────────────────┐
│      通过 BRAT 安装 opencode-obsidian      │
│   BRAT 设置 → Add Beta plugin             │
│   输入: mtymek/opencode-obsidian           │
└──────────────────┬───────────────────────┘
                   │
                   ▼
┌──────────────────────────────────────────┐
│           安装 OpenCode CLI               │
│   npm i -g opencode-ai                   │
└──────────────────┬───────────────────────┘
                   │
                   ▼
┌──────────────────────────────────────────┐
│         启用插件，开始使用                  │
│   Ctrl+Shift+O 打开面板                   │
│   直接在 Obsidian 里使用 OpenCode         │
└──────────────────────────────────────────┘

一句话总结：装 BRAT → 搜 mtymek/opencode-obsidian → 装好 OpenCode CLI → Ctrl+Shift+O 开始用。就这么简单。

📚 参考来源：

opencode-obsidian GitHub 仓库

BRAT 插件 GitHub 仓库

OpenCode 官方文档

知识管理 on Yanmu

OpenCode + Obsidian：打造你的AI驱动知识管理工作流

📋 目录

一、什么是 opencode-obsidian 插件？

二、环境准备

三、安装 BRAT 插件

步骤 1：打开社区插件市场

步骤 2：搜索并安装 BRAT

四、通过 BRAT 安装 opencode-obsidian

步骤 1：打开 BRAT 设置

步骤 2：添加 Beta 插件

步骤 3：输入仓库地址

步骤 4：启用插件

自动更新

五、安装 OpenCode CLI

六、插件设置详解

基础设置

界面设置

上下文注入（实验性）

自定义命令

七、首次使用

打开 OpenCode 面板

首次启动流程

验证一切正常

快捷键速查

八、上下文注入（实验性功能）

开启方式

注入的内容

使用场景

局限性

九、自定义命令模式

什么时候需要自定义命令？

配置步骤

命令模板

⚠️ 重要注意事项

十、常见问题与故障排除

❌ 找不到 OpenCode 可执行文件

❌ 服务启动超时

❌ 面板显示空白

❌ 面板无法嵌入

❌ 中文文件名乱码（Windows）

❌ 插件更新后需要重新配置

总结