forked from Selig/openclaw-skill
Selig
4c966a3ad2
6 custom skills (assign-task, dispatch-webhook, daily-briefing, task-capture, qmd-brain, tts-voice) with technical documentation. Compatible with Claude Code, OpenClaw, Codex CLI, and OpenCode.
313 lines
12 KiB
Markdown
313 lines
12 KiB
Markdown
# 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 分鐘執行
|