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）

❌ 外掛更新後需要重新配置

總結