📋 目录

• 一、什么是 opencode-obsidian 插件？
• 二、环境准备
• 三、安装 BRAT 插件
• 四、通过 BRAT 安装 opencode-obsidian
• 五、安装 OpenCode CLI
• 六、插件设置详解
• 七、首次使用
• 八、上下文注入（实验性功能）
• 九、自定义命令模式
• 十、常见问题与故障排除

一、什么是 opencode-obsidian 插件？

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

核心特性：

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

适用场景：

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

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

二、环境准备

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

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

三、安装 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：

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

首次启动流程

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

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

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

验证一切正常

在 OpenCode 界面中输入：

1

/help

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

1

/models

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

快捷键速查

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

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

开启方式

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

注入的内容

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

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

使用场景

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

局限性

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

• 在 OpenCode 界面中创建新 Session 时，上下文不会自动注入
• 上下文更新有一定的延迟

九、自定义命令模式

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

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

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

配置步骤

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

命令模板

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 环境变量。

解决方案：

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

1

where opencode.cmd

2. 将输出的完整路径填入插件设置的「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 更新插件时会保留你的设置数据。如果发现设置丢失，重新进入设置页面配置即可。

总结

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

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

┌──────────────────────────────────────────┐
│           安装 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 官方文档