---
title: "OpenCode 實戰：免費 API、地端 Ollama、Code Graph MCP 與 Skill 的全方位整合指南"
description: "第一人稱實測 OpenCode：免費雲端模型、地端 Ollama 整合、Code Graph MCP、MCP 文件查詢與瀏覽器除錯、專案級 Skill 設定，一款工具搞定 AI 輔助開發全流程。"
canonical_url: "https://blog.markkulab.net/post/opencode-cloud-free-models-ollama-mcp-skill-pitfall-guide"
author: "Mark Ku"
author_url: "https://blog.markkulab.net/author/mark-ku"
site: "Mark Ku's Blog"
date_published: "2026-11-07T02:40:45.000Z"
category: "AI"
tags: ["OpenCode", "AI Agent", "MCP", "Code Graph", "Ollama", "免費模型", "免費 API"]
language: "zh-TW"
license: "CC BY 4.0"
license_url: "https://creativecommons.org/licenses/by/4.0/"
attribution: "轉載或引用請註明作者並附上原文連結"
---

# OpenCode 實戰：免費 API、地端 Ollama、Code Graph MCP 與 Skill 的全方位整合指南

## 前言：為什麼我又換了一個 AI 編碼工具？

這幾年 AI 編碼工具換了一輪又一輪，每套工具各自為政：模型切換、MCP 設定、專案 Prompt 管理散在不同地方，換一台電腦就要重新設定一次。我想要的其實很單純：**一個開源、模型中立、設定檔可以跟著 Repo 走的 CLI／桌面版代理**，能同時接雲端免費模型、付費模型、地端 Ollama，再掛上 MCP 與專案級 Skill。

OpenCode 剛好就是這樣的工具。同一份 `opencode.json`，在公司、家裡桌機、甚至內網環境都能用，成本可控、隱私可管，團隊新人拉下 Repo 執行 `opencode` 就能上手。這篇把我目前的設定、踩過的坑和建議起手式一次整理，給還在猶豫的工程師參考。

## 核心優勢：一個工具吃遍所有模型與生態

OpenCode 最大的賣點是「聚合器」定位，不綁單一模型商，四個支柱一次到位：

*   **模型聚合**：目前有 13 個左右 input／output 都是 $0 的免費模型（`deepseek-v4.1-flash-free`、`glm-5.3-flash-free`、`big-pickle`、視覺用的 `nemotron-3.5-super-vl-free` 等），終端機輸入 `opencode models` 或在 TUI 打 `/models` 就能看到完整清單。付費模型也在同一個介面切換，參考價格：DeepSeek V4.1 Flash `$0.30/$1.20`、Claude Sonnet 5.5 `$2/$10`（每 1M tokens）。
*   **地端模型**：`opencode.json` 直接指向內網的 Ollama，依場景挑模型：`qwen3-vl:8b` 看圖、OCR，`qwen3-coder:30b` 日常 coding，MoE 架構的 `qwen3.6-35b-a3b` 只啟用 3B 參數，速度快。
*   **MCP 原生支援**：Context7、瀏覽器三件組、GitHub 都能直接寫進設定檔，不用另外包一層。
*   **Skill 機制**：技能放在專案的 `.opencode/skills/` 底下跟著 Repo 走，除錯流程、TDD 習慣、React 最佳實踐全團隊一致，代理變成「懂專案規矩」的隊友。
*   **Code Graph MCP**：最新的 Code Graph MCP 支援大型專案的深度探索，只需一次呼叫就能回傳相關符號的原始碼加上呼叫路徑和影響範圍摘要，取代了 grep 加 Read 的迴圈。

## 實戰設定：從安裝到跑起第一個 Task

### 安裝與啟動

最簡單的是官方安裝腳本，或用 npm 全域安裝：

```bash
curl -fsSL https://opencode.ai/install | bash
# 或
npm install -g opencode-ai
```

也可以直接下載桌面版。終端機執行 `opencode` 進入 TUI，輸入 `/models` 確認模型清單有正常載入。

### 雲端免費模型

我平常先用 `deepseek-v4.1-flash-free` 跑一般 coding 任務，回應速度不錯，很適合原型開發和副專案。但有幾點要先知道：

*   **限時免費**：隨時可能下架，別把它當成永久方案。
*   **有限速但沒公布數字**：尖峰時段會感覺得到變慢。
*   **只能在 OpenCode 裡用**：免費 chat 模型不能拿 API key 餵給別的 client，需要登入 OpenCode Console 或設定 `OPENCODE_API_KEY`。
*   **注意隱私**：NVIDIA 系列明講不要放機密資料；DeepSeek、GLM、Beam 則是零保留。

### 接地端 Ollama 完整步驟

這是我花最多時間調的地方，坑主要在 context 長度和跨主機連線。

**1. 伺服器端啟動參數（一定要加）：**

```bash
# 把 context 拉到 32K，並開放其他主機連線
OLLAMA_CONTEXT_LENGTH=32768 \
OLLAMA_HOST=0.0.0.0:11434 \
ollama serve
```

> 💡 **關鍵提醒**：Ollama 預設 context 常常只有 4K～8K，模型讀到一半就「突然失憶」，工具呼叫也容易失敗。官方文件也建議遇到 tool call 不正常時先把 context 拉到 16K～32K。跨主機連線記得開防火牆的 11434 埠。

**2. 客戶端 `opencode.json`：**

Ollama 走 OpenAI 相容 API，所以 provider 要指定 `@ai-sdk/openai-compatible`，`baseURL` 記得帶 `/v1`：

```json
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "Ollama (內網)",
      "options": {
        "baseURL": "http://192.168.1.100:11434/v1"
      },
      "models": {
        "qwen3-coder:30b": { "name": "Qwen3 Coder 30B" },
        "qwen3-vl:8b": { "name": "Qwen3 VL 8B" },
        "qwen3.6-35b-a3b": { "name": "Qwen3.6 35B A3B (MoE)" }
      }
    }
  },
  "model": "ollama/qwen3-coder:30b"
}
```

`192.168.1.100` 換成你自己 Ollama 主機的 IP；同一台機器就用 `localhost`。

**3. 驗證：** 重新啟動 OpenCode，`/models` 應該會出現地端模型，選一個丟個小任務測看看就知道通不通。

### 地端模型怎麼挑

| 模型 | 大小 | 適合場景 |
| :--- | :--- | :--- |
| `qwen3-vl:8b` | 6.2 GB | 看圖、OCR，16 GB RAM 就能跑 |
| `qwen3-coder:30b` | 18.6 GB | 日常 coding，建議 32 GB RAM |
| `qwen3.6-35b-a3b` | 22.1 GB | MoE 只啟用 3B，速度快 |
| `qwen3.5:35b` | 22 GB | 比較複雜的任務 |

## MCP 與 Skill：把代理變成「懂我專案」的隊友

### MCP 怎麼裝

MCP 寫在 `opencode.json` 的 `mcp` 區塊，`type: "local"` 是在本機啟動指令，`type: "remote"` 是連遠端網址。不想手寫的話，終端機執行 `opencode mcp add` 會一步步引導你設定。

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "context7": {
      "type": "remote",
      "url": "https://mcp.context7.com/mcp",
      "enabled": true
    },
    "playwright": {
      "type": "local",
      "command": ["npx", "-y", "@playwright/mcp@latest"],
      "enabled": true
    },
    "chrome-devtools": {
      "type": "local",
      "command": ["npx", "-y", "chrome-devtools-mcp@latest"],
      "enabled": true
    }
  }
}
```

### 三個瀏覽器 MCP 各做各的事

我裝了三個瀏覽器相關的 MCP，一開始常搞混，後來抓到分工就很順：

| 情境 | 用哪個 | 原因 |
| :--- | :--- | :--- |
| 要登入的頁面（後台、信箱、公司系統） | browse（操作已登入的 Chrome） | 直接沿用你瀏覽器裡的登入狀態 |
| 寫 E2E 測試、重現 bug | playwright | 乾淨的瀏覽器環境，步驟可以重播 |
| 查 Console 錯誤、Network、效能、記憶體 | chrome-devtools | 拿得到 DevTools 層級的資訊 |

一句話記：**要登入用 browse、寫測試用 playwright、查錯誤用 chrome-devtools。**

### Context7：查官方文件不再瞎掰

裝了 Context7 之後，代理問到 Next.js、Prisma、Tailwind 這類函式庫的用法時，會先去拉最新官方文件，不會憑印象亂寫參數。版本更新快的框架特別有感。

### GitHub MCP：要 Token

GitHub MCP 可以直接操作 repo、issue、PR、Actions，但要先設定 `GITHUB_PERSONAL_ACCESS_TOKEN`。我第一次裝完發現工具數是 0，原因就是 token 沒設。

### Code Graph MCP：大型專案的深度探索

Code Graph 是 OpenCode 最新支援的 MCP，專為大型專案設計。它是一個 SQLite 知識圖譜，索引專案的符號、邊和檔案，支援 30 多種語言。

**Code Graph 的核心優勢：**

- **一次呼叫，全方位探索**：`codegraph_explore` 只需一次呼叫，就能回傳相關符號的原始碼加上呼叫路徑和影響範圍摘要，取代了 grep 加 Read 的迴圈
- **快速查詢**：支援符號名稱、檔案名稱、短語搜尋
- **流程探索**：探索程式碼流程，比如某個函式如何呼叫另一個函式
- **影響範圍分析**：修改某段程式碼會影響哪些地方
- **多專案查詢**：可以同時索引多個專案，跨專案追蹤依賴關係

**實戰應用：**

```json
{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "codegraph": {
      "type": "local",
      "command": ["npx", "-y", "@opencode/codegraph-mcp@latest"],
      "enabled": true
    }
  }
}
```

**使用情境：**
- 想要了解某個函式被哪些地方呼叫
- 修改 API 後想知道會影響哪些模組
- 追蹤跨專案的依賴關係
- 分析大型專案的呼叫圖

**與 Context7 的差異：**
- **Context7**：查官方文件，確保使用正確的 API 參數
- **Code Graph**：查專案內部，了解專案的呼叫關係和影響範圍

兩者搭配使用，既能掌握外部函式庫的最新用法，又能理解專案內部的依賴關係。

### Skill：把團隊做法寫成檔案

Skill 是一個資料夾配一個 `SKILL.md`，放在專案的 `.opencode/skills/<名稱>/SKILL.md`，跟著 Repo 版控。OpenCode 也會讀 `.claude/skills/`，原本給 Claude Code 寫的技能可以直接共用。例如建立 `.opencode/skills/debug/SKILL.md`：

```markdown
---
name: debug
description: 團隊標準除錯流程，遇到 bug 時使用
---

# 除錯技能

遇到 Bug 時，請依照以下步驟：

1.  **先看 Log**：收集 Console、Server Log、錯誤堆疊。
2.  **再推測**：根據錯誤訊息列出 3 個可能原因，標註信心度。
3.  **再改 Code**：針對最有可能的原因做最小範圍修正，並寫測試驗證。
4.  **複盤**：在 PR 描述記錄根因與修正邏輯。
```

代理碰到 bug 時就會照這套流程走，不會一上來就亂改程式。同樣的方式可以建 TDD、React 最佳實踐、測試撰寫等技能。

## 坑與限制：免費不代表沒有代價

*   **免費模型隨時可能下架**：重要工作流不要只綁一個免費模型，地端或付費模型要當備援。
*   **Ollama context 陷阱**：預設 4K～8K 不夠用，**一定要設 `OLLAMA_CONTEXT_LENGTH=32768`**；跨主機記得 `OLLAMA_HOST=0.0.0.0:11434`。
*   **地端吃硬體**：30B 等級的模型建議 32 GB RAM 起跳；MoE 模型雖然快，複雜重構還是付費模型比較穩。
*   **隱私邊界**：機密程式碼不要送到明講不保證隱私的免費模型，這種任務就交給地端模型。

## 結論：適合誰？我的建議起手式

### 適合

*   想省訂閱費、需要內網或離線開發的工程師
*   希望設定檔進版控、「設定即文件」的團隊
*   喜歡用 MCP、Skill 打造自動化流程的人

### 不適合

*   不想碰 JSON 設定、想要全託管介面的人
*   已經深度綁定其他 AI 編碼工具、短期沒打算換的團隊

### 建議起手式

1.  **先用免費模型**：安裝後 `/models` 挑 `deepseek-v4.1-flash-free` 之類的免費模型，先跑幾個日常任務感受一下。
2.  **接地端 Ollama**：照上面的 `provider` 設定加進 `opencode.json`，記得把 context 拉到 32K。
3.  **裝 MCP 基礎套件**：
    - **Context7**：查官方文件，確保使用正確的 API 參數
    - **playwright**：寫 E2E 測試、重現 bug
    - **chrome-devtools**：查 Console 錯誤、Network、效能、記憶體
    - **Code Graph**（大型專案必備）：深度探索專案結構和呼叫關係
4.  **寫第一個 Skill**：從團隊最常重複說明的流程開始，例如除錯或 code review。

如果你也在找一個可攜帶、可擴充、不綁廠商的 AI 編碼夥伴，OpenCode 很值得試試看。

## 參考連結

*   [OpenCode 官方文件](https://opencode.ai/docs)
*   [從 Copilot 到 Cursor 到 Claude：用 Claude Code Hook 在開發中自動提煉知識文件](https://blog.markkulab.net/post/ai-tools-sharing-claude-gemini)
*   [Claude Code 進階玩法，GitHub Web 開發、Hook 知識庫、Remote Control 與常用 MCP](https://blog.markkulab.net/post/claude-code-tips-and-tricks)
*   [Docker 安裝AI大型語言模型 Ollama ，並實測比較CPU與GPU硬體加速效能](https://blog.markkulab.net/post/build-your-ollama-ai-with-hardware-acceleration)
*   [先工具、再 MCP、最後 Agent：用 Hermes Agent 打造全地端 AI 助理](https://blog.markkulab.net/post/hermes-agent-local-mcp-lora)
*   [Vibe Coding 經驗分享](https://blog.markkulab.net/post/ai-dev-experience-sharing)

---

## 關於本文與作者

本文出自 [Mark Ku's Blog](https://blog.markkulab.net/post/opencode-cloud-free-models-ollama-mcp-skill-pitfall-guide)

授權條款： [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) — 轉載或引用請註明作者並附上原文連結

### 關於作者

**[Mark Ku](https://blog.markkulab.net/author/mark-ku)** — 軟體工程師

- 10 年以上軟體工程師
- 做過北美電商與 AI SaaS 訂閱收費系統

### 作者開發的免費工具

以下工具皆可免費使用：

- [免費 PDF 簽名工具](https://blog.markkulab.net/tools/pdf-sign): 線上 PDF 簽名工具，瀏覽器內完成手繪、打字、上傳簽名，可拖曳放置、縮放、下載。所有處理都在你的裝置完成，檔案不會上傳。
- [VS Code Refactory](https://blog.markkulab.net/tools/refactory): Refactory 是一款 VS Code 重構擴充套件：34 個重構動作、37 條 code smell 檢查、Code Health 儀表板、18 種語言、534 支測試。懂你的專案慣例：介面放哪、DI 註冊寫在哪、'use client' 該不該加；還會用 git 修改頻率 × 複雜度排出「該先修哪個檔案」，並一鍵把壞味道交給你自己電腦上的 Claude Code 修。免費使用，原始碼不離開你的機器。
- [DB-Kit 資料庫管理工具](https://blog.markkulab.net/tools/db-kit): DB-Kit 是一個用 Tauri + Rust + React 打造的輕量跨平台資料庫管理工具，用單一一致的介面同時管理 MySQL、MariaDB、PostgreSQL、SQL Server、Oracle、SQLite、MongoDB、Redis、Kafka、Elasticsearch 與 RabbitMQ 十一種資料來源：連線密碼以 OS keychain 加密、SSH Tunnel、完整 CRUD、視覺化查詢建構器、多結果集同時顯示、跨連線資料傳輸、結構與資料比對（同步 SQL、結構快照）、Excel / CSV 匯入匯出、執行計畫視覺化、ER 圖、排程備份、SQL 壓力測試（p50～p99 延遲百分位）、15 條規則的 SQL 審查、執行前 AI 審查並逐句備份的「審查並執行」（自動產生回滾腳本）、Kafka 訊息瀏覽與監控告警、SSH 終端機與 SFTP / FTP、Docker / Kubernetes、遠端桌面（RDP / VNC / RustDesk）、檔案 / 資料夾比對、預存程序整合測試；六種介面語言，內建 AI 助手（本機 CLI 或 Anthropic / OpenAI 相容 API，自然語言生成 SQL、AI 審查與調校建議）與命令列工具 dbk。免費開源（MIT），提供 Windows / macOS / Linux 安裝檔。
- [VS Code Super Mermaid](https://blog.markkulab.net/tools/super-mermaid): Super Mermaid 是一款 VS Code 擴充套件：開箱即用的漂亮 Mermaid 圖表，自動上色、即時預覽、滑鼠平移縮放、PNG / SVG 高解析匯出，內建 21 種範本與多種主題。免費開源（MIT）。
- [React Super Mermaid](https://blog.markkulab.net/tools/react-super-mermaid): react-super-mermaid 是一個開源 React 元件庫：一行 <MermaidViewer> 即可渲染漂亮的 Mermaid 圖表，內建 colorful / sketch 主題、平移縮放、圖內搜尋、SVG / PNG 高解析匯出。輕量、SSR 安全、完整 TypeScript 型別。免費開源（MIT）。
- [Jira / Confluence Super Mermaid](https://blog.markkulab.net/tools/jira-super-mermaid): Atlassian Forge app：在 Jira issue 與 Confluence 內文直接寫 Mermaid 語法，畫流程圖、時序圖、狀態機與甘特圖。11 種圖表、SVG / PNG 匯出、明暗主題、完整中日韓文字支援。取得 Runs on Atlassian 資格：圖表存在你自己的站台，app 不呼叫任何第三方服務。免費，即將上架 Atlassian Marketplace。
- [Mermaid 線上預覽](https://blog.markkulab.net/tools/mermaid-preview): 在瀏覽器裡寫 Mermaid、即時看圖，整張圖表壓進網址就能分享。免註冊、不上傳伺服器，相容 mermaid.live 的分享連結。
- [React Intl Phone Number](https://blog.markkulab.net/tools/react-intl-phone-number): react-intl-phone-number 是一個開源 React 元件：framework-agnostic、不依賴 antd，提供 E.164 進出、可搜尋國旗 / 國碼下拉、可配置驗證等級（strict / mobile-strict / loose）、可主題化 CSS 與 i18n，電話邏輯由 google-libphonenumber 驅動。輕量、完整 TypeScript 型別。免費開源（MIT）。
- [Uptime Kuma Cluster](https://blog.markkulab.net/tools/uptime-kuma-cluster): 把單機版 Uptime Kuma 改造成高可用叢集：OpenResty + Lua 智慧負載平衡、MariaDB 共享狀態、健康檢查與自動 Failover，附監控與叢集管理 RESTful API，一行 Docker Compose 啟動。免費開源（MIT）。
- [AI Podcast Cut 音檔剪輯](https://blog.markkulab.net/tools/ai-podcast-cut): 丟進一段錄音，AI 幫你剪掉「嗯、呃、那個」與講到一半重講的片段，平衡逐段音量，並派第二個 agent 覆核每一刀。辨識與去人聲都在你自己的電腦上跑，不上傳、不需要金鑰。剪點會貼齊字邊界與零交越、每一刀都有漸弱漸強，句尾還留得住呼吸感。Windows / macOS / Linux 桌面應用，MIT 開源，Windows 安裝檔內建 ffmpeg。
- [AI Video Cut 影片剪輯](https://blog.markkulab.net/tools/ai-video-cut): 在影片裡選一個東西：打字（人臉、車牌、手機螢幕、logo）、手動點選或拖框，或交給 Claude Code / Codex 挑。AI Video Cut 會逐幀追蹤它，再幫你打馬賽克或模糊、調色、加跟著走的貼紙與文字、把螢幕或海報換成你的圖片或影片，甚至用其他幀拍到的背景把它移除。另有序列剪輯、本機字幕與 AI 助手。免費開源（MIT）的 Windows 桌面應用（macOS / Linux 實驗中），本機運行，影片不上傳。
- [open-pos 開源餐飲 POS](https://blog.markkulab.net/tools/open-pos): 一台電腦加一台出單機就能開店。資料存在自己的硬碟裡、沒有月租、沒有綁約，MIT 全開源。金額用整數元依營業稅法拆算稅額，銷售額加稅額恆等於總額；出單走網路型 ESC/POS（TCP 9100），不必裝廠商驅動。Tauri + Rust + SQLite 桌面應用，v1.0 開發中。
- [.NET 電商 API 架構範本](https://blog.markkulab.net/tools/dotnet-ecommerce-api): 以 .NET 10 打造的電商平台後端 API 架構範本：Controller → Service → Repository 分層、Autofac 依命名慣例自動註冊、SqlSugar 支援 MySQL / MariaDB 與 SQL Server、Redis 快取與訊息佇列、Hangfire 排程、JWT 認證，內建可擴充的金流 Provider 模組（綠界 ECPay、藍新 Newebpay）。Apache 2.0 開源。
- [Open Token Monitor 團隊 AI 用量監控](https://blog.markkulab.net/tools/open-token-monitor): 把每位員工電腦上 AI coding 工具的 token 用量與等值成本集中到公司自架的 hub：PostgreSQL、組織名單、依公司與部門比較的 dashboard、報表 API。員工端有 Electron 與 Rust/Tauri 兩種，每 30 分鐘自動上傳。MIT 開源，Docker 一行起。
- [AI 資安監控 ai-security-monitor](https://blog.markkulab.net/tools/ai-security-monitor): 網站上線了，漏洞、憑證與安全設定誰來檢查？ai-security-monitor 用自架 Security Hub 集中網站掃描與主機監控，合併重複發現、比對修補前後，讓你知道哪些問題還沒處理。

### 每日 Podcast

- [Mark's Tech Insights 每日 AI 新鮮事](https://blog.markkulab.net/category/tech-news): 每日精選 AI 與科技趨勢，透過語音摘要快速掌握最新技術動態，涵蓋 AI 應用、軟體架構、DevOps 與工程實戰。 — RSS: https://blog.markkulab.net/feed.xml
- [AI股市蝦聊](https://blog.markkulab.net/category/ai-stock-chat): 每個交易日用 AI 分析台股盤勢，以雙人對話聊當天的盤中觀察與隔日預測。 — RSS: https://blog.markkulab.net/ai-stock-chat/feed.xml
- [開源好物日報](https://blog.markkulab.net/category/open-source-weekly): 每天從 Hacker News、GitHub、Reddit 聲量雷達精選免費開源工具，以雙人對話聊解決什麼痛點與怎麼快速上手。 — RSS: https://blog.markkulab.net/open-source-weekly/feed.xml
- [AI 運動日報](https://blog.markkulab.net/category/sports-weekly): 每天以雙人對話聊 NBA、MLB 與國際體壇大事，台灣球迷視角，輕鬆有梗不酸人。 — RSS: https://blog.markkulab.net/sports-weekly/feed.xml
- [AI 國際新聞快報](https://blog.markkulab.net/category/world-news): 每天早上以雙人對話把過去一天的國際大事講白：政治外交、全球經濟、衝突與安全、災害與氣候，台灣視角、中立客觀、每則附出處。 — RSS: https://blog.markkulab.net/world-news/feed.xml
- [地端 AI 實驗室](https://blog.markkulab.net/category/local-ai-lab): 每天精選可以下載到自己機器上跑的開源模型與 LoRA，用雙人對話講清楚能用在哪些場景、你的顯卡跑不跑得動、跟同類差在哪，規格一律引述官方 model card。 — RSS: https://blog.markkulab.net/local-ai-lab/feed.xml
- [AI 行銷日報](https://blog.markkulab.net/category/ai-marketing): 每天以雙人對話整理最新 AI 在行銷、廣告、SEO／GEO 與內容行銷的大事，實戰視角、不業配、每則附出處。 — RSS: https://blog.markkulab.net/ai-marketing/feed.xml
- [AI 資安日報](https://blog.markkulab.net/category/ai-security): 每天以雙人對話整理最新 AI 與資安交會的大事：LLM 與 AI agent 漏洞、prompt injection、模型供應鏈、攻擊者怎麼用 AI，防禦視角、每則附出處。 — RSS: https://blog.markkulab.net/ai-security/feed.xml

### 電子報

[訂閱電子報](https://blog.markkulab.net/subscribe) — 第一時間收到新文章通知，無垃圾信、隨時可取消訂閱。