快速開始：安裝與配置
學完你能做什麼
在本課中，你將學會：
- 將 opencode-supermemory 外掛安裝到你的 OpenCode 環境中。
- 配置 Supermemory API Key，打通雲端記憶庫。
- 驗證外掛是否成功載入。
- 解決與其他外掛（如 Oh My OpenCode）的潛在衝突。
完成後，你的 Agent 將具備連接雲端記憶庫的基礎能力。
你現在的困境
你可能已經發現，OpenCode 的 Agent 雖然聰明，但它很健忘：
- 每次開啟新會話，它都像失憶了一樣，不記得你之前的偏好。
- 你在專案 A 裡教過它的架構規範，到了專案 B 它又忘了。
- 長時間的會話聊著聊著，前面的關鍵資訊就被「擠」出了上下文。
你需要一個外掛大腦，幫 Agent 記住這些東西。
什麼時候用這一招
- 第一次使用：當你剛接觸 opencode-supermemory 時。
- 重裝環境：當你遷移到新電腦或重設了 OpenCode 配置時。
- 排查問題：當你懷疑外掛沒裝好，或者 API 連線有問題時。
🎒 開始前的準備
在開始之前，請確保你已經：
- 安裝了 OpenCode：確保
opencode指令在終端機可用。 - 取得 API Key：
- 存取 Supermemory Console
- 註冊/登入帳號
- 建立一個新的 API Key（以
sm_開頭）
什麼是 Supermemory？
Supermemory 是一個專門為 AI Agent 設計的雲端記憶層。它不僅能儲存資料，還能透過語意搜尋幫 Agent 在對的時候想起對的事情。
核心思路
安裝過程非常簡單，本質上就是三步走：
- 安裝外掛：執行安裝腳本，註冊外掛到 OpenCode。
- 配置金鑰：告訴外掛你的 API Key 是什麼。
- 驗證連線：重新啟動 OpenCode，確認 Agent 能看到新工具。
跟我做
第 1 步：安裝外掛
我們提供了兩種安裝方式，選擇適合你的一種。
# 推薦：會有互動式引導，幫你自動處理配置
bunx opencode-supermemory@latest install# 如果你是讓 Agent 幫你安裝，請用這個指令（跳過互動確認並自動解決衝突）
bunx opencode-supermemory@latest install --no-tui --disable-context-recovery你應該看到： 終端機輸出 ✓ Setup complete!，表示外掛已成功註冊到 ~/.config/opencode/opencode.jsonc。
第 2 步：配置 API Key
外掛需要 API Key 才能讀寫你的雲端記憶。你有兩種配置方式：
方式 A：環境變數（推薦）
直接在你的 Shell 配置檔（如 .zshrc 或 .bashrc）中新增：
export SUPERMEMORY_API_KEY="sm_你的金鑰..."方式 B：配置檔案
或者，建立一個專門的配置檔案 ~/.config/opencode/supermemory.jsonc：
{
"apiKey": "sm_你的金鑰..."
}為什麼：環境變數更安全，且不會意外提交到程式碼庫；配置檔案則更方便管理多項設定。
第 3 步：解決衝突（如果你用了 Oh My OpenCode）
如果你安裝了 Oh My OpenCode，它自帶的上下文管理功能可能會與 Supermemory 衝突。
檢查方法： 安裝腳本通常會自動偵測並提示你停用衝突的鉤子。如果沒有，請手動檢查 ~/.config/opencode/oh-my-opencode.json：
{
"disabled_hooks": [
"anthropic-context-window-limit-recovery" // ✅ 確保這一行存在
]
}為什麼：Supermemory 提供了更智慧的「搶佔式壓縮」（Preemptive Compaction），如果兩個外掛同時嘗試管理上下文，會導致混亂。
第 4 步：驗證安裝
重新啟動 OpenCode，然後執行檢查指令：
opencode -c或者直接進入 OpenCode 互動模式，查看工具列表。
你應該看到： 在工具列表（Tools）中，出現了 supermemory 工具。
Available Tools:
- supermemory (add, search, profile, list, forget)
...檢查點 ✅
請自檢以下項目，確保一切就緒：
- [ ] 執行
cat ~/.config/opencode/opencode.jsonc，能看到"opencode-supermemory"在plugin列表中。 - [ ] 環境變數
SUPERMEMORY_API_KEY已生效（可以用echo $SUPERMEMORY_API_KEY檢查）。 - [ ] 執行
opencode後，Agent 沒有報錯提示。
踩坑提醒
常見錯誤：API Key 沒生效
如果你設定了環境變數但外掛提示未認證，請檢查：
- 你是否重新啟動了終端機？（修改
.zshrc後需要source ~/.zshrc或重新啟動） - 你是否重新啟動了 OpenCode？（OpenCode 程序需要重新啟動才能讀取新變數）
常見錯誤：JSON 格式錯誤
如果你手動修改 opencode.jsonc，請確保 JSON 格式正確（特別是逗號）。安裝腳本會自動處理這個，但手動修改容易出錯。
本課小結
恭喜！你已經成功給 OpenCode 裝上了「海馬體」。現在，你的 Agent 已經準備好開始記憶了。
- 我們安裝了
opencode-supermemory外掛。 - 我們配置了雲端連接憑證。
- 我們排除了潛在的外掛衝突。
下一課預告
下一課我們學習 專案初始化：建立第一印象。
你會學到：
- 如何用一條指令讓 Agent 深度掃描整個專案。
- 如何讓 Agent 記住專案的架構、技術堆疊和隱性規則。
- 如何查看 Agent 到底記住了什麼。
附錄：原始碼參考
點擊展開查看原始碼位置
更新時間：2026-01-23
| 功能 | 檔案路徑 | 行號 |
|---|---|---|
| 安裝腳本邏輯 | src/cli.ts | 327-410 |
| 外掛註冊邏輯 | src/cli.ts | 195-248 |
| 衝突偵測邏輯 | src/cli.ts | 273-320 |
| 配置檔案載入 | src/config.ts | - |