# OpenClaw + WSL + Ollama + ngrok + LINE 本地部署完整指南

> 紀錄日期：2026-03-15
>
> 環境：Windows 11 + WSL2 (Ubuntu) + i7-12700h (筆電) + NVIDIA RTX 3050 Ti 4GB + RAM 32GB

***

## 環境架構

Windows 11
└── WSL2 (ubuntu_openclaw)
    ├── Ollama（背景服務，port 11434）
    │   ├── qwen3.5:4b
    │   ├── qwen3.5:9b
    │   ├── qwen3.5-4b-32k（自訂 32k context 版本）
    │   └── qwen3.5-9b-32k（自訂 32k context 版本）
    ├── OpenClaw（gateway，port 18789）
    │   └── Web UI：http://localhost:18789
    └── ngrok（Webhook 轉發，port 18789 → HTTPS 公開網址）

***

## 安裝步驟

### 1. 建立專用 WSL Distro

# 若沒有現有 distro，先安裝 Ubuntu
wsl --install Ubuntu

# 備份乾淨環境
wsl --export <乾淨的 distro 名稱> <匯出位置>

# 匯入為 OpenClaw 專用 distro
wsl --import <distro 名稱> <安裝位置> <匯入位置>

# 啟用
wsl -d <你的 distro 名稱>

### 2. 更新系統與安裝套件

sudo apt update && sudo apt upgrade -y
sudo apt install -y build-essential curl git wget zip unzip npm zstd jq

### 3. 透過 nvm 安裝 Node.js v22

> OpenClaw 需要 Node.js 22+，系統預設版本通常不夠新。

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash

# 重新載入 shell 後執行
nvm install 22
nvm use 22
nvm alias default 22

**讓每次開新終端機自動切到 v22：**

# 確認 nvm 初始化已在 .bashrc（應在第 119~121 行附近）
grep -n "nvm" ~/.bashrc

# 在 nvm bash_completion 那行後面插入自動切換
sed -i '/bash_completion/a nvm use 22 --silent' ~/.bashrc
source ~/.bashrc

### 4. 安裝 Ollama

curl -fsSL https://ollama.com/install.sh | sh

# 確認能正常執行
ollama

> 執行 `ollama serve` 時若出現 `address already in use`，代表服務已在背景運作，屬正常現象。

### 5. 啟用 KV Cache 量化（減少記憶體壓力）

> 建議在拉取模型前完成此設定。`q8_0` 量化可將 KV cache 記憶體用量減半，讓更多模型層留在 VRAM，對速度有顯著幫助，且對輸出品質影響極小。

sudo systemctl edit ollama --force

加入以下內容：

[Service]
Environment="OLLAMA_KV_CACHE_TYPE=q8_0"

儲存後套用：

sudo systemctl daemon-reload
sudo systemctl restart ollama

### 6. 拉取模型

# 推薦先拉 4b（較快驗證環境）
ollama pull qwen3.5:4b

# 確認可正常運作
ollama run qwen3.5:4b "hello"

# 之後再拉 9b
ollama pull qwen3.5:9b

### 7. 建立自訂 32k context 模型

> **為什麼是 32k，不是更小的值？**
>
> OpenClaw 以 agent 模式運作，叫他執行任務（clone repo、讀檔、寫程式）時，每一輪 tool call 的輸入指令與執行結果都會累積進 context，比純對話消耗快很多。幾次 tool call 後就可能撞到上限導致任務卡住。
>
> 此外，OpenClaw 的 compaction 機制（當 context 快滿時自動壓縮對話歷史）需要至少 32k 才能正常運作，低於這個值會在 agent 執行任務時連續 abort，造成整個 agent 卡死。
>
> 因此最低建議使用 32k。OpenClaw 預設的 262144 context 會超出 4GB VRAM 可負擔的量，必須改用自訂版本。

**4b 版本：**

cat > ~/Modelfile4b << 'EOF'
FROM qwen3.5:4b
PARAMETER num_ctx 32768
EOF

ollama create qwen3.5-4b-32k -f ~/Modelfile4b

**9b 版本：**

cat > ~/Modelfile9b << 'EOF'
FROM qwen3.5:9b
PARAMETER num_ctx 32768
EOF

ollama create qwen3.5-9b-32k -f ~/Modelfile9b

確認 num_ctx 正確：

ollama show qwen3.5-9b-32k --modelfile | grep num_ctx

### 8. 安裝並啟用 OpenClaw

ollama launch openclaw

互動介面裡選擇模型（建議先選 `qwen3.5:4b`），OpenClaw 會自動設定 `openclaw.json` 並備份。

啟動成功後終端機會顯示：

✓ OpenClaw is running
  Open the Web UI:
    http://localhost:18789/#token=ollama

> 若出現 npm 相關錯誤，確認 nvm 的 Node.js v22 已正確設為 default。

> **重要：** `ollama launch openclaw` 安裝完後，`openclaw` CLI 的路徑不會自動加進 PATH。需完成步驟 3 的「自動切換 v22」設定，否則每次開新終端機都會出現 `openclaw: command not found`。

### 9. 修正 OpenClaw 設定

**9-1. 使用 jq 更新模型 id/name 與 contextWindow：**

> `openclaw config set` 對 JSON 陣列元素的路徑語法無效，必須用 `jq` 直接操作。

jq '
  .models.providers.ollama.models[0].id = "qwen3.5-4b-32k" |
  .models.providers.ollama.models[0].name = "qwen3.5-4b-32k" |
  .models.providers.ollama.models[0].contextWindow = 32768
' ~/.openclaw/openclaw.json > /tmp/openclaw_tmp.json && mv /tmp/openclaw_tmp.json ~/.openclaw/openclaw.json

確認寫入：

cat ~/.openclaw/openclaw.json | jq '{id: .models.providers.ollama.models[0].id, contextWindow: .models.providers.ollama.models[0].contextWindow}'

**9-2. 設定 primary model：**

openclaw config set agents.defaults.model.primary ollama/qwen3.5-4b-32k

**9-3. 設定 compaction 與 timeout：**

> `reserveTokensFloor` 預設值為 20000，這個值是 compaction 作業所需的保留空間。若 context 總量不夠大，compaction 會直接 abort，造成 agent 執行任務時卡死。必須設為 0 讓 compaction 能正常啟動。

openclaw config set agents.defaults.compaction.reserveTokensFloor 0
openclaw config set agents.defaults.timeoutSeconds 1800

**9-4. 關閉 thinking mode（避免回應過慢）：**

sed -i 's/"reasoning": true/"reasoning": false/' ~/.openclaw/openclaw.json

> 注意：`openclaw config set agents.defaults.model.thinking false` 對此版本會報 validation error，須改用 `sed` 直接修改 json。

**9-5. 重啟 gateway 套用設定：**

openclaw gateway stop && sleep 2 && openclaw gateway start

### 10. 串接 LINE Official Account

#### 10-1. 在 LINE Developers Console 建立 Messaging API Channel

1. 前往 [LINE Developers Console](https://developers.line.biz/console/)
2. 選擇或建立 Provider
3. 點「**Create a Messaging API channel**」
4. 填入必要資訊後送出
5. 建立完成後，LINE 會自動在 [LINE Official Account Manager](https://manager.line.biz/) 產生對應的官方帳號
6. 回到 Developers Console，進入剛建立的 channel
7. 「**Basic settings**」分頁 → 複製並記錄 **Channel Secret**
8. 「**Messaging API**」分頁 → **Channel access token** → 點「**Issue**」產生並複製

#### 10-2. 安裝 LINE Plugin

> 執行前確認 `openclaw` 指令可用（先 `source ~/.bashrc`）

openclaw plugins install @openclaw/line

#### 10-3. 設定 config

openclaw config set channels.line.channelAccessToken "你的_channel_access_token"
openclaw config set channels.line.channelSecret "你的_channel_secret"

確認寫入：

cat ~/.openclaw/openclaw.json | jq '.channels'

#### 10-4. 安裝 ngrok

LINE Webhook 必須是 HTTPS，本地環境需透過 ngrok 轉發：

curl -sSL https://ngrok-agent.s3.amazonaws.com/ngrok.asc \
  | sudo tee /etc/apt/trusted.gpg.d/ngrok.asc >/dev/null && \
echo "deb https://ngrok-agent.s3.amazonaws.com buster main" \
  | sudo tee /etc/apt/sources.list.d/ngrok.list && \
sudo apt update && sudo apt install ngrok -y

前往 <https://dashboard.ngrok.com/signup> 註冊免費帳號，取得 authtoken 後執行：

ngrok config add-authtoken 你的_authtoken

啟動轉發（此視窗需保持開啟）：

ngrok http 18789

另開終端機取得完整網址：

curl http://127.0.0.1:4040/api/tunnels | python3 -m json.tool | grep public_url

#### 10-5. 填入 Webhook URL

1. 前往 Developers Console → 你的 channel →「**Messaging API**」分頁
2. 找到「**Webhook URL**」欄位，填入：

https://xxxxxxxx.ngrok-free.app/line/webhook

> **注意：** 路徑必須是 `/line/webhook`，不是 `/webhooks/line`。

1. 點「**Verify**」確認連線正常（需要 gateway 和 ngrok 同時在跑）
2. 開啟「**Use webhook**」開關

#### 10-6. 設定 LINE Official Account Manager

前往 <https://manager.line.biz/> → 你的帳號 → **Settings → Response settings**：

- **Chat** → **關閉**
- **Webhooks** → **開啟**
- **Auto-response messages** → **關閉**

> 這步驟容易漏做，未開啟 Webhooks 的話 LINE 訊息不會送到 OpenClaw，gateway log 也不會有任何反應。

#### 10-7. 重啟 Gateway 並完成配對

openclaw gateway stop && sleep 2 && openclaw gateway start

從 LINE 傳訊息給 bot，會收到類似：

OpenClaw: access not configured.
Your lineUserId: Uxxxxxxxxx
Pairing code: XXXXXXXX
Ask the bot owner to approve with:
openclaw pairing approve line XXXXXXXX

執行配對：

openclaw pairing approve line <配對碼>

完成後即可透過 LINE 與 OpenClaw AI 對話。

> **注意：** ngrok 免費版每次重啟網址會改變，需重新更新 Developers Console 的 Webhook URL。若要固定網址，可使用 ngrok 付費方案或改用 Cloudflare Tunnel（需自有網域），可參考這裡 [OpenClaw + WSL + Ollama + Cloudflare Tunnel + LINE 本地部署與外部連線 Web UI 完整指南 10-4 步驟](https://hackmd.io/@80hB8lX2SvWaxYO715T4Ig/Sk2rXUX5Zg#10-4-%E8%A8%AD%E5%AE%9A-Cloudflare-Tunnel)。

***

## 遇到的問題與解法

### 問題一：`LLM request timed out` / `model failed to load`

**症狀：**
OpenClaw Web UI 顯示 `Ollama API error 500: model failed to load`。

**原因：**
OpenClaw 預設 `contextWindow: 262144`（262K tokens），要求 Ollama 分配大量 KV cache，遠超過 4GB VRAM 可負擔的量。Xwayland（WSL GUI 服務）額外佔用 600MB~1.5GB，讓可用 VRAM 更少。

**查看 Ollama log 確認：**

journalctl -u ollama -f

Log 會看到 Ollama 不斷嘗試從 7 個 GPU layers 降到 1，最後全部 offload 失敗。

**解法：** 執行步驟 7 建立 32k 自訂模型，並依步驟 9 更新設定。

***

### 問題二：thinking mode 造成回應過慢

**症狀：**
TUI 底部顯示 `think low`，每次回應前都有大量推理過程。

**原因：**
`openclaw.json` 裡模型的 `reasoning` 預設為 `true`。

**解法：**

sed -i 's/"reasoning": true/"reasoning": false/' ~/.openclaw/openclaw.json
openclaw gateway stop && sleep 2 && openclaw gateway start

> 注意：`openclaw config set agents.defaults.model.thinking false` 對此版本會報 validation error，須改用 `sed` 直接修改 json。

***

### 問題三：`100% context used` 對話卡住

**症狀：**
Web UI 底部出現紅色警告 `100% context used`，模型無法繼續回應。

**解法：**
開新對話，點左側「聊天」旁的 **+** 按鈕，或直接在瀏覽器輸入：

http://localhost:18789/chat?session=new

***

### 問題四：切換模型後 Web UI 仍顯示舊模型名稱

**說明：**
這是 UI 快取問題，實際使用的模型以回應訊息下方的 tag 為準。強制重新整理瀏覽器（`Ctrl + Shift + R`）或開新對話後 tag 就會正確顯示新模型名稱。

***

### 問題五：`ollama serve` 報 `address already in use`

**說明：** 這不是錯誤，代表 Ollama 服務已在背景運作，可直接進行後續步驟。

***

### 問題六：`openclaw: command not found`

**原因：**
`openclaw` CLI 安裝在 nvm 管理的 node 路徑下，開新終端機時若 nvm 沒有自動切到 v22，PATH 就不包含 openclaw。

**解法：**

grep "nvm use 22" ~/.bashrc

若沒有，手動加入：

sed -i '/bash_completion/a nvm use 22 --silent' ~/.bashrc
source ~/.bashrc

***

### 問題七：LINE Webhook Verify 回傳 404

**原因：** Webhook URL 路徑填錯。

**正確路徑：**

https://xxxxxxxx.ngrok-free.app/line/webhook

**錯誤路徑（不可用）：**

https://xxxxxxxx.ngrok-free.app/webhooks/line

***

### 問題八：LINE 訊息沒有進到 OpenClaw

**症狀：**
Verify 成功（200 OK），但從 LINE 傳訊息後 ngrok 沒有收到任何 POST，gateway log 也沒反應。

**原因：**
LINE Official Account Manager 的 **Webhooks 開關未開啟**。

**解法：**
前往 <https://manager.line.biz/> → Settings → Response settings → 把 **Webhooks** 開關打開。

***

### 問題九：agent 執行任務到一半卡住，gateway log 出現 compaction 連續失敗

**症狀：**
叫 agent 執行多步驟任務（如 clone repo、讀檔後處理）時，沒有回應，gateway log 出現：

[compaction] Full summarization failed, trying partial: Summarization failed: This operation was aborted
[compaction] Partial summarization also failed: Summarization failed: This operation was aborted

**原因：**
agent 執行任務時，tool call 的輸入輸出快速累積 context，觸發 compaction（自動壓縮對話歷史的機制）。但 OpenClaw 的 `reserveTokensFloor` 預設值為 20000，代表 compaction 啟動時必須保留 20000 tokens 的作業空間。若 context 總量不夠大，compaction 會直接 abort，造成 agent 卡死。

**解法：**

openclaw config set agents.defaults.compaction.reserveTokensFloor 0
openclaw config set agents.defaults.timeoutSeconds 1800
openclaw gateway stop && sleep 2 && openclaw gateway start

> 根本解法是確保使用 32k context model，讓 compaction 有足夠空間正常運作。

***

### 問題十：`openclaw config set` 修改 contextWindow 無效

**症狀：**
執行 `openclaw config set models.providers.ollama.models.contextWindow 32768` 後，`openclaw.json` 裡的值沒有改變。

**原因：**
`models` 欄位是 JSON 陣列，`openclaw config set` 的路徑語法無法定址陣列元素。

**解法：** 使用 `jq` 直接修改：

jq '
  .models.providers.ollama.models[0].id = "qwen3.5-9b-32k" |
  .models.providers.ollama.models[0].name = "qwen3.5-9b-32k" |
  .models.providers.ollama.models[0].contextWindow = 32768
' ~/.openclaw/openclaw.json > /tmp/openclaw_tmp.json && mv /tmp/openclaw_tmp.json ~/.openclaw/openclaw.json

***

### 問題十一：透過 LINE 叫 agent 執行任務時沒有回應

**症狀：**
從 LINE 叫 agent 執行任務（如 clone repo），ngrok log 顯示請求有進來，但 agent 沒有回應。

**原因：**
LINE Webhook 有 **30 秒**硬性 timeout，無法修改。agent 執行任務時需要多輪 tool call，若 model 推理速度太慢（如 context 過大導致 100% CPU offload），就會在 30 秒內無法回應，LINE 端直接切斷連線。

透過 `ollama ps` 可確認 PROCESSOR 欄位是否為 `100% CPU`。

**解法：**
使用 32k context model，在 4GB VRAM 環境下約 74% CPU / 26% GPU offload，推理速度足以在 timeout 前完成 LINE 的簡短指令。

複雜的多步驟 coding 任務建議改用 **Web UI**，不受 30 秒 timeout 限制。

***

## 硬體限制與模型選擇

| 模型 | 大小 | PROCESSOR | 適合情境 | 備註 |
| :---------------------------- | :----- | :---------------- | :----------------------------- | :-------------------------- |
| `qwen3.5:4b`（預設 262k ctx） | 3.4 GB | 無法載入 | - | contextWindow 太大 |
| `qwen3.5-4b-32k`（32k ctx） | 3.4 GB | 完整 GPU | LINE + Web UI 皆可 | **推薦，速度最快** |
| `qwen3.5:9b`（預設 262k ctx） | 6.6 GB | 無法載入 | - | contextWindow 太大 |
| `qwen3.5-9b-32k`（32k ctx） | 6.6 GB | 74% CPU / 26% GPU | LINE 簡單指令、Web UI 複雜任務 | 效果較好，速度可接受 |
| `qwen3.5-9b-128k`（128k ctx） | 6.6 GB | 100% CPU | 僅 Web UI | LINE 30 秒 timeout 必定觸發 |

> RTX 3050 Ti 只有 4GB VRAM，Xwayland 會額外佔用 600MB~1.5GB。啟用 `OLLAMA_KV_CACHE_TYPE=q8_0` 可將 KV cache 記憶體用量減半，改善 GPU offload 比例。

***

## 切換模型

# 切換到 9b
jq '
  .models.providers.ollama.models[0].id = "qwen3.5-9b-32k" |
  .models.providers.ollama.models[0].name = "qwen3.5-9b-32k" |
  .models.providers.ollama.models[0].contextWindow = 32768
' ~/.openclaw/openclaw.json > /tmp/openclaw_tmp.json && mv /tmp/openclaw_tmp.json ~/.openclaw/openclaw.json
openclaw config set agents.defaults.model.primary ollama/qwen3.5-9b-32k

# 切換回 4b
jq '
  .models.providers.ollama.models[0].id = "qwen3.5-4b-32k" |
  .models.providers.ollama.models[0].name = "qwen3.5-4b-32k" |
  .models.providers.ollama.models[0].contextWindow = 32768
' ~/.openclaw/openclaw.json > /tmp/openclaw_tmp.json && mv /tmp/openclaw_tmp.json ~/.openclaw/openclaw.json
openclaw config set agents.defaults.model.primary ollama/qwen3.5-4b-32k

# 重啟套用
openclaw gateway stop && sleep 2 && openclaw gateway start

> 切換後須開新對話，回應 tag 才會正確顯示新模型名稱。

***

## 常用指令速查

# 查看目前 VRAM 使用量
nvidia-smi

# 確認 Ollama 模型列表
ollama list

# 查看目前載入中的模型與 PROCESSOR 比例
ollama ps

# 強制釋放模型佔用的記憶體
ollama stop qwen3.5-9b-32k

# 重啟 OpenClaw gateway
openclaw gateway stop && sleep 2 && openclaw gateway start

# 查看 OpenClaw gateway log
journalctl --user -u openclaw-gateway.service -f

# 查看 Ollama log
journalctl -u ollama -f

# 開啟 TUI
openclaw tui

# 讓 gateway 在關閉終端機後繼續運作
sudo loginctl enable-linger $USER

# 啟動 ngrok（LINE Webhook 用，需保持視窗開啟）
ngrok http 18789

# 取得目前 ngrok 公開網址
curl http://127.0.0.1:4040/api/tunnels | python3 -m json.tool | grep public_url

***

## 備註

- OpenClaw 設定檔位置：`~/.openclaw/openclaw.json`
- OpenClaw Web UI：`http://localhost:18789/#token=ollama`
- Node.js 版本需要 22+，建議透過 nvm 管理，避免系統套件版本過舊
- 新對話入口：左側「聊天」旁的 **+** 按鈕，或網址 `http://localhost:18789/chat?session=new`
- LINE Webhook URL 格式：`https://<ngrok-subdomain>.ngrok-free.app/line/webhook`
- LINE Webhook 有 **30 秒**硬性 timeout，無法修改；複雜的 agent 任務請使用 Web UI
- `openclaw config set` 無法修改 JSON 陣列元素，需改用 `jq`
- ngrok 免費版每次重啟網址會變，固定網址需付費方案或改用 Cloudflare Tunnel（需自有網域）
- LINE Official Account Manager 的 Webhooks 開關需手動開啟，與 Developers Console 的 Use webhook 是兩個不同設定
- `OLLAMA_KV_CACHE_TYPE=q8_0` 設定位於 `/etc/systemd/system/ollama.service.d/override.conf`

## 性能與穩定性最佳化：遷移至雲端 API 解決方案

若同學在部署過程中發現本地硬體資源不足（例如 **RTX 3050 Ti 4GB** 顯存過小），或遇到以下不穩定現象：

- **載入失敗**：頻繁出現 `model failed to load` 或 `Ollama API error 500`。
- **任務卡死**：受限於顯存，Context Window 無法開高，導致 Agent 任務因 `compaction` 失敗而中斷。

建議參考我另一篇雲端遷移指南，改用 **阿里雲百煉 (Qwen)** 作為後端模型以獲得更穩定的體驗：

> **[OpenClaw + 雲模型 Qwen3.5：從本地 Ollama 遷移至阿里雲百煉 (Qwen)](https://hackmd.io/@80hB8lX2SvWaxYO715T4Ig/SyIlD3H9Wl)**

### 遷移至雲端的優勢

- **解除顯存限制**：API 運算不佔用本地 GPU，解決 4GB VRAM 無法處理長文本的困境。
- **提升回應速度**：雲端推理速度顯著優於本地運行，約快 3 至 5 倍。
- **高額免費試用**：目前阿里雲國際版提供新用戶高達 **7,000 萬個 Tokens** 的免費試用額度。
- **穩定支援長文本**：支援 **131K** 以上的 Context Window，確保複雜 Agent 任務順暢執行。