Ollama-x-Opencode 完整設定與使用指南

https://github.com/p-lemonish/ollama-x-opencode

本筆記整合了官方 README.md 的說明以及針對您本地環境的客製化調整，提供一份從零開始的完整設定與使用指南。

1. 先決條件

Git： 用於clone儲存庫。
Docker & Docker Compose： 用於容器化。
NVIDIA GPU（選用但建議）： 用於 GPU 加速的 Ollama。
NVIDIA Container Toolkit： Docker 存取 NVIDIA GPU 所需。

2. 環境設定

2.1 `.env` 檔案設定

在專案根目錄下建立一個 .env 檔案，用於定義 Ollama 資料的儲存路徑。

.env 檔案範例：

OLLAMA_DATA=./data

說明： OLLAMA_DATA 定義了 Ollama 儲存模型和資料的本地路徑。docker-compose.yml 將會讀取此變數。

2.2 Docker 網路

docker-compose.yml 中使用了名為 my-ollama-net 的外部網路。您需要手動建立此網路：

docker network create my-ollama-net

2.3 安裝 NVIDIA Container Toolkit（若無GPU可略過）

請依照您 Linux 發行版的官方 NVIDIA Container Toolkit 安裝指南進行操作。
先準備gpg key

curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg

Ubuntu/Debian 範例（或類似設定）：
安裝後，請確認 /etc/apt/sources.list.d/nvidia-container-toolkit.list 檔案內容應類似如下，以使用穩定版：

deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://nvidia.github.io/libnvidia-container/stable/deb/$(ARCH) /

然後執行：

sudo apt-get update
sudo apt-get install -y nvidia-container-toolkit
sudo systemctl restart docker

驗證安裝：
```
docker run --rm --gpus all ubuntu nvidia-smi
```
成功應會顯示您的 NVIDIA GPU 詳細資訊。

3. 專案啟動與模型設定

3.1 git 儲存庫

git clone https://github.com/p-lemonish/ollama-x-opencode.git
cd ollama-x-opencode

提醒： 請確保上述的 .env 檔案建立在此目錄下。

3.2 確認 `docker-compose.yml`

您的 docker-compose.yml 經過微調，應包含 GPU 支援並使用 my-ollama-net 網路。

services:
  ollama:
    image: ollama/ollama:latest
    container_name: ollama
    restart: unless-stopped
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: all
              capabilities: [gpu]
    healthcheck:
      test: ["CMD", "nvidia-smi"]
      interval: 10s
      timeout: 5s
      retries: 3
      start_period: 1m
    volumes:
      - ${OLLAMA_DATA}:/root/.ollama
    ports:
      - "11434:11434"
    networks:
      - my-ollama-net

networks:
  my-ollama-net:
    external: true

3.3 啟動服務

docker compose up -d

3.4 下載模型

使用 docker compose exec 進入 ollama 容器來下載模型。

docker compose exec ollama ollama pull qwen3:8b

3.5 擴充模型 Context Window (重要)

根據 README.md，Ollama 預設的 context window (4096) 過小，會導致 agentic tools (代理工具) 無法正常運作。您需要手動擴充並儲存成一個新模型。

進入 Ollama 容器互動模式：

docker compose exec ollama ollama run qwen3:8b

設定並儲存新模型：
在 >>> 提示符後，輸入以下指令：
```
/set parameter num_ctx 16384
/save qwen3:8b-16k
/bye
```
這會將 context window 設為 16384，並建立一個名為 qwen3:8b-16k 的新模型。

4. Opencode 設定與使用

4.1 設定 `config.json`

為了讓 Opencode 能使用您剛才建立的本地模型，您需要設定其設定檔。設定檔路徑為 ~/.config/opencode/config.json。

config.json 範例：

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ollama": {
      "npm": "@ai-sdk/openai-compatible",
      "options": {
        "baseURL": "http://localhost:11434/v1"
      },
      "models": {
        "qwen3:8b-16k": {
          "tools": true
        }
      }
    }
  }
}

注意： 這裡的 qwen3:8b-16k 必須與您在步驟 3.5 中儲存的新模型名稱完全相符。

4.2 執行 Opencode

現在您可以執行 Opencode，並透過 --model 參數指定使用剛設定好的 Ollama 模型。

opencode run "產生一個 todo.md 檔案，內容為 'hello world, from qwen3'" --model ollama/qwen3:8b-16k

本筆記是根據官方文件、專案結構以及您的本地端環境配置所彙整的完整指南。

reference

https://github.com/p-lemonish/ollama-x-opencode
這篇文章是 gemini-cli 寫的，我微調