mathruffian-dot/opencode-lazy-packs/01-connect-model

連接免費模型（OpenCode Zen）

官方文件查證日期：2026-07-27

依據：<https://opencode.ai/docs/zen/>、<https://opencode.ai/docs/>、<https://opencode.ai/docs/providers/>、<https://opencode.ai/docs/models/>、<https://opencode.ai/docs/troubleshooting/>

⚠️ 先看這裡：為什麼這包一定要做

裝完 OpenCode 不等於能用。

OpenCode 只是「駕駛座」，它自己不會思考。你必須先幫它接上一顆「腦袋」（模型），它才會回話、才會幫你建檔案、才會操作 NotebookLM。

如果你照 #00 環境建置 裝完，打開 OpenCode 卻發現：

• 打字進去沒有反應
• 跳出 No providers configured 之類的訊息
• 右下角看不到任何模型名稱

那不是你裝壞了，是還沒做這一包。

📌 建議順序：#00 環境建置 → #01 連接模型（本包）→ 其他所有懶人包

沒接模型，後面每一包都跑不動。

這個懶人包會幫你做什麼？

1. 註冊 OpenCode Zen（OpenCode 官方的模型入口）
2. 拿到一組 API key（就是那把鑰匙）
3. 在 OpenCode 裡把鑰匙插進去（桌面版與 CLI 終端機版兩種做法都教）
4. 選一個免費模型
5. 做一次真的會動手的測試（請它建一個 test.txt），確認整條線是通的

原理說明（30 秒看懂）

你  →  OpenCode（駕駛座）  →  OpenCode Zen（模型總機）  →  實際的 AI 模型
                              ↑
                        用 API key 認人

OpenCode Zen 是 OpenCode 官方整理的模型清單。官方文件的原話是：這是一份「經過測試與驗證的模型清單」。

它的好處是：一組 key 通到多個模型，包含一批目前免費的模型。老師不用一家一家去申請 OpenAI、Google、Anthropic 的帳號。

💡 Zen 是選用的，不是強制。官方文件明講「completely optional」。你也可以接自己的其他供應商，但對零程式基礎的老師來說，Zen 是最短路徑。

先備條件

• [ ] 已完成 #00 環境建置（opencode --version 有版本號）
• [ ] 電腦有網路連線
• [ ] 有一個可以收信的 Email 帳號（註冊用）
• [ ] 一個空資料夾，等一下拿來做測試（例如 Documents\opencode-test）

桌面版還是 CLI？兩條路都寫，選一條走完

🔑 步驟一（註冊拿 key）兩條路完全一樣，都要做。

做完再依你的情況跳到 步驟二A（桌面版） 或 步驟二B（CLI）。

桌面版還沒裝？（CLI 使用者可跳過）

#00 環境建置只裝了 CLI。桌面版要另外裝：

• Windows（主線）：開 <https://opencode.ai/download>，下載 Windows 版安裝檔，雙擊安裝
• macOS：同一個下載頁抓 .dmg；或用 Homebrew

``bash brew install --cask opencode-desktop ``

• Linux：同一個下載頁抓 .deb 或 .rpm

請 OpenCode（或你自己）依序執行以下步驟

這份檔案可以整份貼給 AI agent 讓它帶你做。

遇到 🖐️ 圖示的地方是必須人工操作（要登入、要點網頁），agent 會停下來等你。

步驟一：註冊 OpenCode Zen、拿到 API key

🖐️ 這一步全程在瀏覽器裡做。

1-1. 開啟登入頁

網址（官方文件指定的入口）：

https://opencode.ai/auth

這個網址會自動轉到 OpenCode 的登入畫面（auth.opencode.ai）。看到網址變了是正常的，不是被釣魚。

1-2. 登入 / 註冊

用你的 Email（或畫面提供的登入方式）建立帳號並登入。

1-3. 建立 API key

登入後會進到 Console（管理後台）。找到 API Keys 相關的區塊，建立一組新的 key。

畫面上的按鈕字樣可能是 Create API Key 或 Add API Key，也可能藏在 Settings 底下。

官方文件沒有逐格說明後台 UI，以你看到的畫面為準。 只要找到「建立金鑰」的按鈕就對了。

1-4. 複製並保管好

⚠️ API key 通常只會完整顯示一次。 建立後立刻複製。

保管建議（給老師）：

• 先貼到「記事本」暫存，確認整串在同一行、前後沒有多餘空白、沒有被自動換行切開
• ❌ 不要貼到共用的 Google 文件、班級群組、簡報備忘稿
• ❌ 不要放進之後要上傳 GitHub 的資料夾
• ✅ 之後真的要存，存在自己的密碼管理器裡

1-5. 關於「帳單資料」

官方文件的流程原話是：登入 → 加入帳單資料 → 複製 API key。

實務上請這樣處理：

1. 先直接嘗試建立 API key
2. 如果後台不讓你建、明確要求先填付款資料，才依畫面指示處理
3. 學校公務機／不想綁卡的老師，到這裡先停下來問承辦或自行決定，不要在研習現場趕著輸入信用卡

❓ 本包無法從官方文件確認：「只用免費模型」是否也一定要先填帳單資料。官方 /docs/zen/ 沒有針對免費模型另外說明。請以你當下看到的後台畫面為準。

💰 本懶人包不寫任何金額、儲值額度、扣款門檻。價格會變，一律以官方 <https://opencode.ai/docs/zen/> 的 Pricing 表為準。

步驟二A：桌面版連接（研習現場走這條）

🖐️ 需要人工點畫面。

1. 打開 OpenCode 桌面版
2. 進入 Settings（設定）
3. 找到 Providers（供應商） 這一區
4. 找到 OpenCode Zen（找不到就用搜尋框打 zen 或 opencode；清單可能要點「顯示更多供應商」才會全部展開）
5. 點 Connect（連接）
6. 把步驟一複製的 API key 貼上，按 Continue / 確認
7. 完全關閉桌面版再重新打開

⚠️ 第 7 點不要跳過。 新加的供應商常常要重啟才會出現在模型清單裡。

ℹ️ 桌面版的實際選單文字官方文件未逐項載明（官方只寫了 CLI 的 /connect 流程），版本不同字樣可能微調。找不到就認關鍵字：Settings → Providers → Connect。

桌面版連不起來？有兩個備援

備援 1：在聊天框直接打指令

有些版本的桌面版聊天輸入框也吃斜線指令。試著輸入：

/connect

跳出選單就照 步驟二B 的流程走。

備援 2：用 CLI 連，桌面版接手

桌面版背景跑的是同一支 OpenCode 伺服器（官方 Troubleshooting 稱為 opencode-cli sidecar），憑證是同一份。所以：

1. 照 步驟二B 用終端機把 key 連好
2. 完全關閉桌面版再重開
3. 模型清單裡就會出現 OpenCode Zen

❓ 「桌面版與 CLI 共用同一份憑證檔」這點官方文件沒有明文寫死，是從「桌面版背景跑 opencode-cli」推得。實測可行率高，但若無效請回到備援 1 或直接用 CLI 工作。

步驟二B：CLI（終端機）連接

Windows 請用 PowerShell，不要用舊的 CMD。

2B-1. 啟動 OpenCode

先切到你的測試資料夾再啟動：

cd ~/Documents/opencode-test
opencode

Windows 找不到資料夾就先建一個：mkdir ~/Documents/opencode-test

2B-2. 輸入連接指令

在 OpenCode 畫面裡輸入：

/connect

2B-3. 選 OpenCode Zen

用方向鍵選 OpenCode Zen，按 Enter。

⚠️ 清單裡還有一個長很像的 OpenCode Go。

那是付費訂閱制方案，不是本包要的。這一包只走 OpenCode Zen。

2B-4. 貼上 API key

畫面會出現輸入框，貼上 key 後按 Enter：

┌ API key
│
│
└ enter

貼上小技巧：Windows PowerShell 裡按滑鼠右鍵通常就是貼上。貼完先看一眼有沒有整串進去。

2B-5. 確認憑證存進去了

離開 OpenCode，在終端機執行：

opencode auth list

清單裡要看得到 OpenCode Zen 相關的項目。

憑證存在哪？（官方 Troubleshooting 明列）

- macOS / Linux：~/.local/share/opencode/auth.json

- Windows：按 WIN+R，貼上 %USERPROFILE%\.local\share\opencode

⚠️ 這個檔案裡面就是你的 API key 明文。不要備份到雲端硬碟、不要 commit 進 Git。

2B-6. 也可以用純指令連（進階）

不想進畫面選單的話：

opencode auth login

它一樣會問你要連哪一家、要你貼 key。

步驟三：選一個免費模型

3-1. 打開模型清單

在 OpenCode 裡輸入：

/models

（快捷鍵：ctrl+x 然後 m）

CLI 也可以直接列出 Zen 的所有模型：

opencode models opencode

這裡的 opencode 是 OpenCode Zen 在設定檔裡的供應商代號（provider id）。

3-2. 怎麼認出哪個是免費的

不要背清單，學會自己查。 免費方案變動很快，官方隨時會加、會下架。

三個查法，可信度由高到低：

3-3. 2026-07-27 當下查到的免費模型（⚠️ 清單會變，僅供參考）

以下是 2026-07-27 於官方 /docs/zen/ Pricing 表查到、標示為 Free 的模型：

🔴 這張表一定會過期。

官方對這些模型的原文說明是「免費為限時提供（available for a limited time）」——廠商在收集回饋、改進模型的期間才免費。

你在讀這份文件的當下，請務必回到 <https://opencode.ai/docs/zen/> 的 Pricing 表重新確認一次。

這份表格的功能是「讓你知道長什麼樣子」，不是「照抄就能用」。

3-4. 在設定檔裡怎麼寫

模型的完整 ID 格式是 供應商代號/模型代號。OpenCode Zen 的供應商代號是 `opencode`。

所以完整寫法長這樣：

opencode/big-pickle
opencode/deepseek-v4-flash-free

步驟四：驗證真的通了（⭐ 不要跳過）

「AI 有回話」不代表通了。 對老師來說真正有用的是「它會幫我動手做事」。

有些便宜或免費的模型很會聊天，但不會正確呼叫工具（不會建檔、不會讀檔）——這種模型接上去，後面的 NotebookLM、Obsidian、生圖懶人包全部會失敗，而且錯誤訊息看起來完全不像模型的問題。

所以驗證要驗「會不會動手」。

4-1. 測試指令（桌面版與 CLI 通用）

在你的測試資料夾開啟 OpenCode，貼進去這段：

請在目前這個資料夾建立一個檔案叫 test.txt，
內容寫一行：OpenCode 連線成功。
建立完成後，把這個檔案的內容讀出來給我看。

4-2. 三個都要看到才算通過

只有 ① 沒有 ②③ → 模型的 tool calling 不行，換一個免費模型重測。

4-3. CLI 一行驗證（懶人版）

opencode run --model opencode/big-pickle "請在目前資料夾建立 test.txt，內容寫：OpenCode 連線成功"

跑完檢查檔案：

ls test.txt        # macOS / Linux
dir test.txt       # Windows

--model 後面請換成你在步驟三查到、當下真的免費的那個 model id。

4-4. 測完清乾淨

rm test.txt        # macOS / Linux
del test.txt       # Windows

步驟五（選用）：把常用模型設成預設

每次開都要重選很煩，可以寫進設定檔。

設定檔位置（官方 Troubleshooting 明列）：

• macOS / Linux：~/.config/opencode/opencode.json
• Windows：按 WIN+R，貼上 %USERPROFILE%\.config\opencode（檔名 opencode.json 或 opencode.jsonc）

內容：

{
  "$schema": "https://opencode.ai/config.json",
  "model": "opencode/big-pickle"
}

⚠️ JSON 常見地雷：最後一項後面不能有逗號；所有引號要用英文半形 "，不能用中文全形「」。

檔案不存在就直接新建一個。

怎麼判斷「這個模型適不適合這個任務」

呼應 OpenCode 基本功 EP06「各種模型正確用法全解析」。

核心觀念：沒有最強的模型，只有適合這個任務的模型。

四個判準（照這個順序想）

任務對照表（實務建議）

給老師的三條實用心法

1. 從最便宜的開始，卡住再往上換。 不要一開始就用最貴的——大部分教學情境，免費模型就夠了。
2. 換模型不用重做設定。 key 只連一次；之後 /models 隨時換，換完下一句話就生效。
3. 同一個任務失敗兩次以上，先換模型再懷疑自己。 很多「懶人包跑不動」其實是模型不會用工具，不是步驟寫錯。

📎 官方 /docs/models/ 也點出同一件事：市面上模型很多，但同時擅長寫程式又擅長呼叫工具的只有少數。這正是我們在步驟四要測「會不會建檔」的原因。

🔒 隱私提醒（免費模型特別重要）

官方 /docs/zen/ 的 Privacy 段落白紙黑字寫著：

• 這些模型在免費期間，收集到的資料可能被用來改進模型
• 其中 North Mini Code Free 與 Nemotron 3 Ultra Free 官方另外加註：請勿提交個人或機密資料

翻成老師聽得懂的話：

用免費模型時，你打進去的東西有可能被對方留下來訓練模型。

老師守則（請直接遵守）

• ❌ 不要丟：學生姓名、學號、身分證字號、成績單、輔導紀錄、家長聯絡方式、班級名冊
• ❌ 不要丟：學校內部公文、未公開的試題
• ✅ 可以丟：公開教材、自己寫的教案、講義草稿、程式碼、示範用的假資料
• ✅ 需要處理真實學生資料時：把姓名換成「學生A、學生B」再丟，或改用有零留存政策的付費模型

這條規則跟省錢無關，是個資保護。研習現場請務必提醒。

常見失敗與排除

如果連錯了，怎麼砍掉重來

對 OpenCode 說：「我的 OpenCode Zen 連錯了，幫我清掉重連。」

或手動依序做：

第 1 級：重連（最常用，先試這個）

/connect

再選一次 OpenCode Zen、貼新的 key，會直接覆蓋舊的。

第 2 級：先移除再連

opencode auth list      # 看目前連了哪些
opencode auth logout    # 依提示移除指定的供應商
opencode auth login     # 重新連

第 3 級：重置設定（最後手段）

官方 Troubleshooting 針對 ProviderInitError 的作法是刪掉 OpenCode 的資料目錄：

• macOS / Linux：~/.local/share/opencode
• Windows：%USERPROFILE%\.local\share\opencode

🔴 警告：這會一併清掉你過去的對話紀錄與 session 資料。 前兩級都試過才用。

刪完要重跑 /connect 重新連。

如果是 key 本身有問題：回 <https://opencode.ai/auth> 的 Console，把舊 key 刪掉、建一把新的，再回來重連。

❓ 本包無法從官方文件確認的項目（現場請自行驗證）

✅ 成功訊號（機器可判讀）

以下全部成立才算完成本包：

CHECK_1  `opencode auth list` 輸出包含 OpenCode Zen 的項目
CHECK_2  `/models`（或 `opencode models opencode`）能列出 Zen 的模型清單，且清單非空
CHECK_3  目前選用的 model id 格式為 opencode/<model-id>，且該模型在官方 Pricing 表標示為 Free
CHECK_4  對 agent 下「建立 test.txt」指令後，agent 實際觸發了寫檔工具（非只用文字回覆）
CHECK_5  test.txt 於測試資料夾中實際存在，且內容與指令一致
CHECK_6  測試完成後 test.txt 已刪除

任一項為 FAIL → 到「常見失敗與排除」對照處理，不要往下做其他懶人包。

完成回報格式

## OpenCode 模型連接完成
 
-OpenCode 版本：<版本>
-操作路徑：桌面版 / CLI
-Zen 帳號註冊：成功 / 失敗
-API key 取得：成功 / 失敗
-憑證寫入（opencode auth list）：CHECK_1 PASS / FAIL
-模型清單可列出：CHECK_2 PASS / FAIL
-選用模型：opencode/<model-id>（免費 / 付費）
-免費狀態查證日期：<YYYY-MM-DD>（依官方 /docs/zen/ Pricing 表）
-工具呼叫測試：CHECK_4 PASS / FAIL
-test.txt 建立驗證：CHECK_5 PASS / FAIL
-測試檔已清除：CHECK_6 PASS / FAIL
-預設模型是否寫入 opencode.json：是 / 否
-隱私提醒已告知使用者：是 / 否
 
### 待處理
-<把 FAIL 的項目與原因列在這裡；全部 PASS 就寫「無」>

下一步

模型接通了，OpenCode 才真正「活了」。接著可以做：