tiangong/openclaw-skill
1
0
Fork 0
forked from Selig/openclaw-skill
Code Pull Requests Activity
Files
4c966a3ad2ed65b6590b6703ea04be727a5aaf88
openclaw-skill/chapters/04-known-issues.md
Selig 4c966a3ad2 Initial commit: OpenClaw Skill Collection 
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.
2026-03-13 10:58:30 +08:00

12 KiB
Raw Blame History

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：
# 永久設定（/etc/sysctl.conf）
net.ipv6.conf.all.disable_ipv6=1
net.ipv6.conf.default.disable_ipv6=1
net.ipv6.conf.lo.disable_ipv6=1
  1. gateway.env 加入 NODE_OPTIONS：
NODE_OPTIONS=--dns-result-order=ipv4first --no-network-family-autoselection
  1. openclaw.json config 層覆蓋（Node 24 必須，因 OpenClaw 內部 hardcode autoSelectFamily:true）：
{ "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

修復：

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 節

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：

"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 綁定：

"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 記錄：

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"

修復：在後端核准配對請求

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。

修復：

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

修復：

# 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：
{
  "browser": {
    "profiles": {
      "openclaw": {
        "cdpUrl": "http://127.0.0.1:18801",
        "color": "#FF4500"
      }
    }
  }
}
  1. 確認 Gateway service 有 Environment=DISPLAY=:99（~/.config/systemd/user/openclaw-gateway.service）

驗證：

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 層級覆蓋：

{
  "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 卡死

診斷流程：

# 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 恢復）：

# 關閉 autoRecall，讓 agent 不依賴 embedding 即可啟動
openclaw config set plugins.entries.memory-lancedb-pro.config.autoRecall false
# Gateway 會自動偵測 config 變更並重啟

根治：重開機修復 GPU driver

預防：停用系統休眠

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 分鐘執行
View Git Blame Copy Permalink