📋 目錄

• 一、什麼是 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 官方文件