# 4. 已知問題與修復

### 4.1 Node.js 22/24 fetch 無法連線 Telegram API

**症狀**：`Telegram: failed - fetch failed`，但 curl 可以正常連線

**根因**：Node.js 22+ 的 `fetch`（基於 undici）有 `autoSelectFamily`（happy eyeballs），優先嘗試 IPv6。伺服器沒有可用的 IPv6 對外連線。

**修復（三層）**：

1. 系統層停用 IPv6：
```bash
# 永久設定（/etc/sysctl.conf）
net.ipv6.conf.all.disable_ipv6=1
net.ipv6.conf.default.disable_ipv6=1
net.ipv6.conf.lo.disable_ipv6=1
```

2. gateway.env 加入 NODE_OPTIONS：
```
NODE_OPTIONS=--dns-result-order=ipv4first --no-network-family-autoselection
```

3. openclaw.json config 層覆蓋（**Node 24 必須，因 OpenClaw 內部 hardcode `autoSelectFamily:true`**）：
```json
{ "channels": { "telegram": { "network": { "autoSelectFamily": false, "dnsResultOrder": "ipv4first" } } } }
```

**注意**：sysctl + NODE_OPTIONS 在 Node 22 就夠了，但 Node 24 的 undici 不吃這些設定，必須用 openclaw.json config 覆蓋（見 §4.13）。

### 4.2 OpenClaw 腳本顯示「未運行」

**症狀**：`sudo bash kejilion.sh app OpenClaw` 顯示「已安裝 未運行」，但 Gateway 實際在跑

**根因**：腳本用 `pgrep -f "openclaw gateway"` 判斷，但 pm2/systemd 啟動的進程名稱不符

**修復**：改用 tmux 啟動（若要讓腳本正確識別），或改用 systemd（推薦）

### 4.3 Docker nginx 開機後無法啟動

**症狀**：`nginx: bind() to 0.0.0.0:80 failed (98: Address in use)`

**根因**：系統安裝的 nginx（`/usr/sbin/nginx`）設為 enabled，開機時搶先佔用 port 80

**修復**：
```bash
sudo systemctl stop nginx
sudo systemctl disable nginx
```

### 4.4 Multi-Agent Config Schema 與文件不符（v2026.2.17）

**症狀**：修改 `openclaw.json` 後 Gateway 啟動失敗，報 `Unrecognized key: "agentId"` 和 `bindings.0.match: Invalid input`

**根因**：官方文件範例使用舊版 schema，與實際 v2026.2.17 不相容

**正確格式**：
- `agents.list[].id`（不是 `agentId`）
- `bindings[]` 需要 `{ "agentId": "xxx", "match": { "channel": "telegram", "accountId": "yyy" } }`
- 詳見 [06-config.md 6.2 節](06-config.md)

### 4.5 新 Bot /start 無配對碼回應

**症狀**：在新 Telegram Bot 按 /start 沒有任何回應

**根因**：按 /start 時 Gateway 尚未載入新 Bot Token，Telegram update 被消耗但無人處理

**修復**：確保 config 已正確 + Gateway 重啟成功後再按 /start

### 4.6 使用 accounts 後主 Bot 通道不啟動（2026-02-25）

**症狀**：`openclaw channels list` 只顯示 `life-bot`，主 Bot（@Cimon168_bot）不啟動，啟動日誌無 `[default] starting provider` 訊息

**根因**：當 `channels.telegram.accounts` 區塊存在時，OpenClaw 只啟動 `accounts` 裡明確列出的帳號。頂層 `botToken` 不再被視為獨立通道。

**修復**：將主 Bot token 從頂層移入 `accounts.default`：

```json
"accounts": {
    "default": {
      "botToken": "<主 Bot Token>"
    },
    "life-bot": {
      "botToken": "<生活 Bot Token>"
    }
}
```

修改後重啟：`systemctl --user restart openclaw-gateway`

### 4.7 Multi-Agent 後 workspace skills 消失（2026-02-25）

**症狀**：Gateway 重啟後 `openclaw skills list` 只顯示 bundled skills，workspace skills（daily-briefing、qmd-brain、task-capture）消失。Agent 回覆不認識這些 skills。

**根因**：`agents.list` 只有具名 agent（如 `life-assistant`）時，隱含的預設 agent（main）不會觸發 workspace skills 掃描。OpenClaw 只對 `agents.list` 中明確列出的 agent 執行 workspace 目錄的 skills 發現。

**修復**：在 `agents.list` 明確加入 `main` agent，並在 `bindings` 加入 `default → main` 綁定：

```json
"agents": {
  "list": [
    {
      "id": "main",
      "name": "主 Agent",
      "model": { "primary": "cliapi/gpt-5.3-codex" },
      "workspace": "/home/selig/.openclaw/workspace"
    },
    { "id": "life-assistant", "..." }
  ]
},
"bindings": [
  { "agentId": "main", "match": { "channel": "telegram", "accountId": "default" } },
  { "agentId": "life-assistant", "match": { "channel": "telegram", "accountId": "life-bot" } }
]
```

修改後重啟：`systemctl --user restart openclaw-gateway`

**驗證**：檢查啟動 log 是否有 workspace skills 的 sanitization 記錄：
```bash
journalctl --user -u openclaw-gateway --since "1 min ago" --no-pager | grep daily-briefing
```

### 4.8 OpenClaw WebUI 配對問題

**症狀**：`https://oclaw.nature.edu.kg/#token=...` 顯示 "backend not paired yet"

**修復**：在後端核准配對請求
```bash
sudo openclaw devices list    # 查看 pending request ID
sudo openclaw devices approve <request-id>
```

### 4.9 升級 2026.2.25 後 Gateway 啟動失敗（2026-02-27）

**症狀**：`Error: Unsafe fallback OpenClaw temp dir: /tmp/openclaw-1000`

**根因**：新版加強 temp 目錄安全檢查，要求 `/tmp/openclaw-<UID>` 權限必須 `700`（owner-only），舊版建立的目錄權限為 `775`。

**修復**：
```bash
chmod 700 /tmp/openclaw-1000    # selig (UID 1000)
# root 的 temp dir 也需清理
sudo rm -rf /tmp/openclaw-0 && sudo mkdir -p /tmp/openclaw-0 && sudo chmod 700 /tmp/openclaw-0
```

### 4.10 升級後 `google-antigravity-auth` plugin 警告（2026-02-27）

**症狀**：`plugin removed: google-antigravity-auth (stale config entry ignored)`

**根因**：`google-antigravity-auth` plugin 已從 2026.2.25 移除，但 `openclaw.json` 仍有殘留設定。

**修復**：從 `openclaw.json` 的 `plugins.entries` 刪除 `google-antigravity-auth` 條目。此 plugin 用於 OpenClaw 直連 Google API 認證，與 CLIProxyAPI 代理的 Gemini 模型無關。

### 4.11 `sudo openclaw skills list` 偵測不到 selig 環境的 CLI（2026-02-27）

**症狀**：`coding-agent` 和 `summarize` 顯示 `✗ missing`，但實際 CLI 已安裝。

**根因**：`sudo openclaw` 以 root 執行，PATH 不含 selig 的 `~/.local/bin` 和 nvm 路徑。

**修復**：使用 `openclaw skills list`（不加 sudo）即可正確偵測。Gateway 以 selig user service 運行，不受影響。

### 4.12 Browser control 連線逾時（2026-03-02）

**症狀**：Telegram Agent 嘗試操控瀏覽器時報 `Browser control service 連線逾時（15 秒）`

**根因**（多層問題）：
1. **Node service 未安裝**：OpenClaw 的瀏覽器控制需要 Node Host service 作為 Gateway 和本機瀏覽器之間的 relay
2. **Node service 未配對**：首次連線 Gateway 時需經過 device pairing 核准
3. **缺少 DISPLAY 環境變數**：Gateway 和 Node service 的 systemd unit 都沒有 `DISPLAY=:99`，導致無法操控 Xvfb 上的瀏覽器
4. **Snap Chromium 限制**：Ubuntu snap 版 Chromium 的包裝器會剝掉 `--load-extension` 和 `--remote-debugging-port` 旗標，無法載入 OpenClaw 擴充套件或啟用 CDP

**修復**：
```bash
# 1. 安裝 Node service 並加入 DISPLAY
openclaw node install
# 編輯 ~/.config/systemd/user/openclaw-node.service 加入 Environment=DISPLAY=:99

# 2. 在 gateway.env 加入 DISPLAY，Gateway service 也要加
echo 'DISPLAY=:99' >> ~/.config/openclaw/gateway.env
# 編輯 ~/.config/systemd/user/openclaw-gateway.service 加入 Environment=DISPLAY=:99

# 3. 啟動 Node service 並配對
systemctl --user daemon-reload
systemctl --user enable --now openclaw-node.service
openclaw devices list          # 等待 pending request
openclaw devices approve <id>  # 核准

# 4. 改用 Playwright Chromium（非 snap，支援 CDP 直連）
# 建立 playwright-chrome.service 並啟用
systemctl --user enable --now playwright-chrome.service

# 5. 建立 cdp-direct profile 設為預設
openclaw browser create-profile --name cdp-direct --cdp-url http://127.0.0.1:18801
# openclaw.json → browser.defaultProfile: "cdp-direct"

# 6. 重啟 Gateway
systemctl --user restart openclaw-gateway
```

### 4.16 Agent browser tool timeout — `openclaw` profile 啟動失敗（2026-03-11）

**症狀**：CLI 的 `openclaw browser navigate` 正常，但 Agent 透過 tool call 使用瀏覽器時 15 秒 timeout：
```
[tools] browser failed: timed out. Restart the OpenClaw gateway...
```

**根因**：v2026.3.7 內建了 `openclaw` browser profile（port 18800），Gateway 啟動時會嘗試用 `detectedPath`（`/usr/bin/chromium-browser`，snap 版）啟動這個 profile。snap Chromium 會剝掉 `--remote-debugging-port` 參數，導致 CDP 永遠無法建立。`openclaw browser profiles` 顯示此 profile 為 `stopped` 狀態。

**關鍵差異**：CLI 指令走 `defaultProfile`（cdp-direct），但 agent tool call 可能嘗試使用 `openclaw` profile。

**修復**：
1. 在 `openclaw.json` 的 `browser.profiles` 覆寫 `openclaw` profile，讓它指向 Playwright CDP：
```json
{
  "browser": {
    "profiles": {
      "openclaw": {
        "cdpUrl": "http://127.0.0.1:18801",
        "color": "#FF4500"
      }
    }
  }
}
```
2. 確認 Gateway service 有 `Environment=DISPLAY=:99`（`~/.config/systemd/user/openclaw-gateway.service`）

**驗證**：
```bash
openclaw browser profiles
# 三個 profile（cdp-direct、chrome、openclaw）都應顯示 running，port 18801
```

### 4.13 Node.js 24 undici autoSelectFamily 導致 Telegram 連線逾時（2026-03-02）

**症狀**：Gateway 重啟後 Telegram 持續 `Network request failed`，但 `curl` 可正常連線 Telegram API

**根因**：Node.js 24 的 `fetch()`（undici）有 `autoSelectFamily`（happy eyeballs），會同時嘗試 IPv4/IPv6。即使系統 sysctl 停用 IPv6 + `NODE_OPTIONS=--dns-result-order=ipv4first`，OpenClaw 內部（`ssrf-D_av5wos.js`）hardcode `autoSelectFamily: true`，覆蓋了 NODE_OPTIONS。

**修復**：在 `openclaw.json` 用 config 層級覆蓋：
```json
{
  "channels": {
    "telegram": {
      "network": {
        "autoSelectFamily": false,
        "dnsResultOrder": "ipv4first"
      }
    }
  }
}
```

同時在 `gateway.env` 的 NODE_OPTIONS 加入 `--no-network-family-autoselection`（雙保險）。

**驗證**：Gateway log 應顯示 `autoSelectFamily=false (config)`

### 4.14 GPU driver suspend/resume 死鎖導致 Bot 全卡（2026-03-02）

**症狀**：所有 Telegram Bot 收到訊息後無回應，`nvidia-smi` 掛起不返回

**根因（三層連鎖故障）**：
1. **系統觸發 suspend/resume** → `nvidia-sleep.sh` 在 kernel 的 `uvm_suspend()` 死鎖（狀態 `Ds` 不可中斷）
2. **GPU driver 無法存取** → llama-embed 的 port 11435 雖然 listen，但 embedding 請求永遠無回應
3. **memory-lancedb-pro 的 `before_agent_start` hook 阻塞** → 每個 agent 啟動時呼叫 embedding API 做 autoRecall，因 llama-embed 無回應而無限等待，導致所有 agent 卡死

**診斷流程**：
```bash
# 1. 確認 GPU 死鎖
timeout 5 nvidia-smi || echo "GPU driver 死鎖"

# 2. 確認 llama-embed 無回應
timeout 5 curl -s http://127.0.0.1:11435/v1/embeddings \
  -H "Content-Type: application/json" \
  -d '{"input":"test","model":"nomic-embed-text-v1.5"}' || echo "embedding 無回應"

# 3. 確認殘留 process
ps aux | grep nvidia-sleep  # 看到 Ds 狀態 = 死鎖
ps aux | grep llama-server  # 可能有殘留舊 process 占住 port
```

**緊急修復（免重開機讓 Bot 恢復）**：
```bash
# 關閉 autoRecall，讓 agent 不依賴 embedding 即可啟動
openclaw config set plugins.entries.memory-lancedb-pro.config.autoRecall false
# Gateway 會自動偵測 config 變更並重啟
```

**根治**：重開機修復 GPU driver

**預防**：停用系統休眠
```bash
sudo systemctl mask sleep.target suspend.target hibernate.target hybrid-sleep.target
```

### 4.15 Embedding 容錯策略（2026-03-02）

llama-embed（GPU）是唯一的 production embedding 路徑。Ollama CPU 模式雖有 `nomic-embed-text`（port 11434，~1.4s/call），但在 4 核心 + 高 load 系統上會拖垮效能，**不適合作為常態 fallback**。

**容錯層級**（由 `~/clawd/scripts/embed-health.sh` 自動執行，cron */30 分鐘，2026-03-02 已實作）：

| 層級 | 條件 | 動作 |
|------|------|------|
| 正常 | llama-embed port 11435 回應 < 2s | `autoRecall: true`, `autoCapture: true` |
| 降級 | llama-embed 無回應或逾時 | 自動設定 `autoRecall: false`, `autoCapture: false`；Telegram 通知使用者 |
| 恢復 | 重開機後 llama-embed 恢復 | 自動設定 `autoRecall: true`, `autoCapture: true`；Telegram 通知 |

**設計原則**：
- 不使用 Ollama CPU fallback（CPU 資源不足）
- 不使用線上 embedding API（隱私考量 + 增加外部依賴）
- embedding 掛了 = 記憶暫停，不影響 Bot 核心回覆功能
- 健康檢查腳本放入 crontab 每 30 分鐘執行