# 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
```powershell
# 若沒有現有 distro，先安裝 Ubuntu
wsl --install Ubuntu
# 備份乾淨環境
wsl --export <乾淨的 distro 名稱> <匯出位置>
# 匯入為 OpenClaw 專用 distro
wsl --import <distro 名稱> <安裝位置> <匯入位置>
# 啟用
wsl -d <你的 distro 名稱>
```
### 2. 更新系統與安裝套件
```bash
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+，系統預設版本通常不夠新。
```bash
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：**
```bash
# 確認 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
```bash
curl -fsSL https://ollama.com/install.sh | sh
# 確認能正常執行
ollama
```
> 執行 `ollama serve` 時若出現 `address already in use`，代表服務已在背景運作，屬正常現象。
### 5. 啟用 KV Cache 量化（減少記憶體壓力）
> 建議在拉取模型前完成此設定。`q8_0` 量化可將 KV cache 記憶體用量減半，讓更多模型層留在 VRAM，對速度有顯著幫助，且對輸出品質影響極小。
```bash
sudo systemctl edit ollama --force
```
加入以下內容：
```ini
[Service]
Environment="OLLAMA_KV_CACHE_TYPE=q8_0"
```
儲存後套用：
```bash
sudo systemctl daemon-reload
sudo systemctl restart ollama
```
### 6. 拉取模型
```bash
# 推薦先拉 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 版本：**
```bash
cat > ~/Modelfile4b << 'EOF'
FROM qwen3.5:4b
PARAMETER num_ctx 32768
EOF
ollama create qwen3.5-4b-32k -f ~/Modelfile4b
```
**9b 版本：**
```bash
cat > ~/Modelfile9b << 'EOF'
FROM qwen3.5:9b
PARAMETER num_ctx 32768
EOF
ollama create qwen3.5-9b-32k -f ~/Modelfile9b
```
確認 num_ctx 正確：
```bash
ollama show qwen3.5-9b-32k --modelfile | grep num_ctx
```
### 8. 安裝並啟用 OpenClaw
```bash
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` 直接操作。
```bash
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
```
確認寫入：
```bash
cat ~/.openclaw/openclaw.json | jq '{id: .models.providers.ollama.models[0].id, contextWindow: .models.providers.ollama.models[0].contextWindow}'
```
**9-2. 設定 primary model：**
```bash
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 能正常啟動。
```bash
openclaw config set agents.defaults.compaction.reserveTokensFloor 0
openclaw config set agents.defaults.timeoutSeconds 1800
```
**9-4. 關閉 thinking mode（避免回應過慢）：**
```bash
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 套用設定：**
```bash
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`）
```bash
openclaw plugins install @openclaw/line
```
#### 10-3. 設定 config
```bash
openclaw config set channels.line.channelAccessToken "你的_channel_access_token"
openclaw config set channels.line.channelSecret "你的_channel_secret"
```
確認寫入：
```bash
cat ~/.openclaw/openclaw.json | jq '.channels'
```
#### 10-4. 安裝 ngrok
LINE Webhook 必須是 HTTPS，本地環境需透過 ngrok 轉發：
```bash
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 後執行：
```bash
ngrok config add-authtoken 你的_authtoken
```
啟動轉發（此視窗需保持開啟）：
```bash
ngrok http 18789
```
另開終端機取得完整網址：
```bash
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 並完成配對
```bash
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
```
執行配對：
```bash
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 確認：**
```bash
journalctl -u ollama -f
```
Log 會看到 Ollama 不斷嘗試從 7 個 GPU layers 降到 1，最後全部 offload 失敗。
**解法：** 執行步驟 7 建立 32k 自訂模型，並依步驟 9 更新設定。
***
### 問題二：thinking mode 造成回應過慢
**症狀：**
TUI 底部顯示 `think low`，每次回應前都有大量推理過程。
**原因：**
`openclaw.json` 裡模型的 `reasoning` 預設為 `true`。
**解法：**
```bash
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。
**解法：**
```bash
grep "nvm use 22" ~/.bashrc
```
若沒有，手動加入：
```bash
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 卡死。
**解法：**
```bash
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` 直接修改：
```bash
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 比例。
***
## 切換模型
```bash
# 切換到 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 才會正確顯示新模型名稱。
***
## 常用指令速查
```bash
# 查看目前 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 任務順暢執行。
Sign in via Google
Sign in via Facebook
Sign in via X(Twitter)
Sign in via GitHub
Sign in via Dropbox
Sign in with Wallet
Connect another wallet