OpenClaw安裝配置常見問題排查

OpenClaw 安裝配置捉蟲記錄：真實踩坑 + 解決方案

2026-03-14·小周 & Opus 4.8

OpenClaw 安裝配置捉蟲記錄：真實踩坑 + 解決方案

作者： 小周 & Opus 4.8 時間： 2026 年 3 月 背景： 從零搭建 OpenClaw（AI Agent 網關）+ 中轉 API，運行在 Vultr VPS 上，通過 Telegram 實現手機操控 AI 生產內容、自動發 X 推文、生成小紅書卡片的完整工作流。

一路走來遇到了無數坑，這篇把每個坑都記錄下來，希望能幫後來人少走彎路。

PS. 如果你遇見某個問題，直接把解決方案餵給 AI，讓它直接動手 fix。當然，如果用的 AI 不夠聰明的話，可能無法修復 :)

1. VPS 基礎設施篇

🐛 Bug #1：Node.js 22 的 IPv6 連接卡死

症狀：

OpenClaw Gateway 啓動後，Telegram Bot 不響應，日誌出現 fetch fallback: forcing autoSelectFamily=false，偶爾直接卡住不動。

根因：

Node.js 22 改變了默認的 DNS 解析順序，啓用了 autoSelectFamily，會優先嚐試 IPv6。但 Vultr 的雙棧 VPS 上 IPv6 連接不穩定，導致 DNS 請求超時或連接掛起。

修復： 
# 方案 A：強制 IPv4 優先（推薦）

export NODE_OPTIONS="--dns-result-order=ipv4first"



方案 B：系統級禁用 IPv6（更徹底）


sysctl -w net.ipv6.conf.all.disable_ipv6=1


sysctl -w net.ipv6.conf.default.disable_ipv6=1
教訓： Node.js 大版本升級的默認行爲變更會悄無聲息地搞死你的服務。VPS 上跑 Node.js 22+，第一件事就是設 --dns-result-order=ipv4first。

🐛 Bug #2：SSH 密碼含特殊字符導致 sshpass 失敗

症狀：

用 sshpass 做自動化部署腳本時，命令莫名失敗，但手動輸密碼沒問題。

根因：

Vultr 生成的隨機密碼裏含 }、% 等 shell 特殊字符，sshpass -p 'xxx' 在某些情況下會被 shell 解釋。

修復： 
# 用 printf 寫到文件，避免任何 shell 轉義問題

printf '%s' 'YOUR_COMPLEX_PASSWORD' > /tmp/.sshpw


sshpass -f /tmp/.sshpw ssh -p 2222 root@45.32.108.90 "hostname"


rm /tmp/.sshpw
教訓： Shell 密碼傳遞永遠用 -f 讀文件，不要用 -p 傳參數。

2. OpenClaw Gateway 篇

🐛 Bug #3：Telegram Bot 409 Conflict 衝突

症狀：

Bot 完全無響應，日誌報 409: Conflict: terminated by other getUpdates request。

根因：

多個 OpenClaw 實例同時輪詢同一個 Telegram Bot Token。常見場景：

  • 之前在前臺跑了一個，又 systemctl start 了一個
  • 舊服務器和新服務器同時在跑
  • 手動 openclaw gateway 和後臺 daemon 同時存在
修復： 
# 1. 殺掉所有 OpenClaw 進程

pkill -9 -f openclaw-gateway



2. 等 30 秒讓 Telegram API 釋放連接


sleep 30



3. 只啓動一個實例


systemctl --user start openclaw-gateway
教訓： Telegram Bot API 的 long-polling 是獨佔式的，全球只允許一個連接。遷移服務器時一定要先把舊的停掉！

🐛 Bug #4：Bot "假活" —— 無聲卡死 (Silent Hanging)

症狀： openclaw gateway status 顯示 Running，但 Bot 完全不響應消息。日誌文件最後更新時間停在幾小時前。 根因：

Telegram 的 long-polling 連接超時後沒有觸發錯誤，OpenClaw 以爲還在正常工作，但實際上已經收不到消息了。這是長連接服務的經典問題。

修復：

寫了���個 crontab watchdog，每 2 分鐘檢查日誌文件大小是否增長：

#!/bin/bash

/root/oc-watchdog.sh



LOG="/tmp/openclaw/openclaw-$(date +%Y-%m-%d).log"


MARKER="/tmp/oc-lastsize"



CURRENT=$(wc -c < "$LOG" 2>/dev/null || echo 0)


LAST=$(cat "$MARKER" 2>/dev/null || echo 0)



if [ "$CURRENT" = "$LAST" ] && [ "$LAST" != "0" ]; then


echo "$(date): bot log stale, restarting" >> /tmp/oc-watchdog.log


export XDG_RUNTIME_DIR=/run/user/0


export DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/0/bus


systemctl --user restart openclaw-gateway


fi



echo "$CURRENT" > "$MARKER"
# crontab -e

*/2 * * * * /root/oc-watchdog.sh
教訓： 長連接服務必須有外部健康檢查，不能只靠進程存活狀態判斷。日誌是否在增長是最簡單有效的健康指標。

🐛 Bug #5：Discord Bot 無法讀取消息內容

症狀：

Discord Bot 在線，能看到消息，但所有消息內容都是空的，AI 無法回覆。

根因：

Discord 2023 年起要求 Bot 必須開啓 Privileged Gateway Intents（特權網關意圖），特別是 Message Content Intent。不開的話 Bot 收到的消息 content 全是空字符串。

修復：
  • 去 Discord Developer Portal → 選你的 App → Bot
  • 開啓所有三個 Privileged Gateway Intents：

- ✅ Message Content Intent

- ✅ Server Members Intent

- ✅ Presence Intent

另外，Discord 的配置結構和 Telegram 不同，必須用 accounts.default.token 而不是直接放 botToken：

"discord": {

"enabled": true,


"accounts": {


"default": {


"token": "YOUR_DISCORD_BOT_TOKEN"


}


}


}
教訓： Discord 的 API 權限模型比 Telegram 複雜得多，一定要檢查 Intents 設置。

3. Claude Relay Service (CRS) 中轉服務篇

🐛 Bug #6：CRS 500 Internal Server Error (zstd 壓縮炸彈)

症狀：

通過中轉服務調用 Claude API 時，隨機出現 500 Internal Server Error，直連 Anthropic 沒問題。

根因：

CRS v1.1.279 及更早版本會把客戶端的 accept-encoding: zstd 直接透傳給上游 Anthropic API。當上遊返回 zstd 壓縮的響應時，CRS 自己解析不了，JSON 解析失敗，返回 500。

修復： 
cd ~/claude-relay-service

git pull


docker-compose pull


docker-compose up -d

升級到 v1.1.290+，這個版本包含了 commit f0b21fdc，會攔截 zstd 透傳。

教訓： 中轉服務一定要及時更新。壓縮編碼問題非常隱蔽——你在日誌裏只看到 500，根本想不到是 zstd 導致的。

4. Anthropic SDK 底層 Bug 篇

🐛 Bug #7：SSE 流中斷導致 Agent 崩潰 (我們提了 PR！🎉)

症狀：

OpenClaw 在處理長對話時隨機崩潰，錯誤信息：

AnthropicError: Unexpected event order, got message_start before receiving "message_stop"
根因：

這是 Anthropic SDK 的一個硬傷。當中轉服務（如 CRS）在上游中斷後��新傳輸 SSE 流時，SDK 會收到一個新的 message_start 事件，但舊的流還沒發 message_stop。SDK 的默認行爲是直接 throw，導致整個 Agent 運行崩潰。

修復：

我們寫了一個 patch 文件，修改 SDK 的 MessageStream.mjs：

- throw new AnthropicError(Unexpected event order, got ${event.type} before receiving "message_stop");

+ // 中轉/代理重傳時可能收到重複的 message_start，


+ // 不要崩潰，丟棄舊的不完整消息，從新消息重新開始


+ __classPrivateFieldSet(this, _MessageStream_currentMessageSnapshot, undefined, "f");


+ return event.message;



    

  • throw new AnthropicError(Unexpected event order, got ${event.type} before "message_start");
    • 



+ // 靜默忽略上一個（中斷的）流的殘留事件


+ return undefined;
教訓：
  • SDK 的異常處理不應該直接崩潰，特別是在有中轉層的場景下
  • 這個 bug 我們已經提了 PR 給 Anthropic，希望能合併
  • Patch 文件保存在 patches/anthropic-sdk-sse-resilience.patch
已經提交社區了 ↑ 開心 🎉

5. Telegram / Discord 集成篇

🐛 Bug #8：Telegram Bot 配對後仍無法響應

症狀：

Bot 配對成功（openclaw pairing approve 通過），但發消息無回覆。

根因：

多種可能：

  • allowFrom 白名單沒有加你的 Telegram User ID
  • groupPolicy 設爲 allowlist 但沒有配羣組 ID
  • Gateway 沒有重啓導致配置未生效
修復： 
# 確保你的 ID 在白名單裏

openclaw config set channels.telegram.allowFrom '["YOUR_TG_USER_ID"]'



重啓 Gateway


systemctl --user restart openclaw-gateway

快速排查清單

遇到問題時，按以下順序排查：

步驟檢查項命令
1Node.js 版本node --version
2IPv6 問題export NODE_OPTIONS="--dns-result-order=ipv4first"
3進程衝突ps aux \grep openclaw
4日誌是否增長ls -la /tmp/openclaw/
5Telegram 409殺掉所有進程，等 30 秒，重啓
6Discord Intents檢查 Developer Portal 權限
7CRS 版本docker-compose pull && docker-compose up -d
8白名單配置openclaw config get channels.telegram.allowFrom

還是解決不了？

如果以上方案都無法解決你的問題：

  • 聯繫管理員

- Telegram: @zhoumo_828

- 微信: Moumlbius

  • 提供以下信息

- 操作系統版本

- Node.js 版本

- 完整的錯誤信息

- 已嘗試的解決方案

作者： 小周 & Opus 4.8 發佈時間： 2026-03-14 字數： 3,247 字 閱讀時間： 約 12 分鐘 PS. 這篇文章會持續更新，遇到新坑就加進來。歡迎在留言區分享你的踩坑經歷！

🚀 立即體驗 youragent

官方 1:1 倍率，價格僅需官方 4%。支持 Cursor、VS Code、Claude Code 等全工具鏈。

聯繫管理員獲取 API Key
OpenClawInstallConfigTroubleshooting

OpenClaw Troubleshooting Guide: Real Bugs & Solutions

2026-03-14·youragent Team

OpenClaw 安裝配置捉蟲記錄：真實踩坑 + 解決方案

作者： 小周 & Opus 4.8 時間： 2026 年 3 月 背景： 從零搭建 OpenClaw（AI Agent 網關）+ 中轉 API，運行在 Vultr VPS 上，通過 Telegram 實現手機操控 AI 生產內容、自動發 X 推文、生成小紅書卡片的完整工作流。

一路走來遇到了無數坑，這篇把每個坑都記錄下來，希望能幫後來人少走彎路。

PS. 如果你遇見某個問題，直接把解決方案餵給 AI，讓它直接動手 fix。當然，如果用的 AI 不夠聰明的話，可能無法修復 :)

1. VPS 基礎設施篇

🐛 Bug #1：Node.js 22 的 IPv6 連接卡死

症狀：

OpenClaw Gateway 啓動後，Telegram Bot 不響應，日誌出現 fetch fallback: forcing autoSelectFamily=false，偶爾直接卡住不動。

根因：

Node.js 22 改變了默認的 DNS 解析順序，啓用了 autoSelectFamily，會優先嚐試 IPv6。但 Vultr 的雙棧 VPS 上 IPv6 連接不穩定，導致 DNS 請求超時或連接掛起。

修復： 
# 方案 A：強制 IPv4 優先（推薦）

export NODE_OPTIONS="--dns-result-order=ipv4first"



方案 B：系統級禁用 IPv6（更徹底）


sysctl -w net.ipv6.conf.all.disable_ipv6=1


sysctl -w net.ipv6.conf.default.disable_ipv6=1
教訓： Node.js 大版本升級的默認行爲變更會悄無聲息地搞死你的服務。VPS 上跑 Node.js 22+，第一件事就是設 --dns-result-order=ipv4first。

🐛 Bug #2：SSH 密碼含特殊字符導致 sshpass 失敗

症狀：

用 sshpass 做自動化部署腳本時，命令莫名失敗，但手動輸密碼沒問題。

根因：

Vultr 生成的隨機密碼裏含 }、% 等 shell 特殊字符，sshpass -p 'xxx' 在某些情況下會被 shell 解釋。

修復： 
# 用 printf 寫到文件，避免任何 shell 轉義問題

printf '%s' 'YOUR_COMPLEX_PASSWORD' > /tmp/.sshpw


sshpass -f /tmp/.sshpw ssh -p 2222 root@45.32.108.90 "hostname"


rm /tmp/.sshpw
教訓： Shell 密碼傳遞永遠用 -f 讀文件，不要用 -p 傳參數。

2. OpenClaw Gateway 篇

🐛 Bug #3：Telegram Bot 409 Conflict 衝突

症狀：

Bot 完全無響應，日誌報 409: Conflict: terminated by other getUpdates request。

根因：

多個 OpenClaw 實例同時輪詢同一個 Telegram Bot Token。常見場景：

  • 之前在前臺跑了一個，又 systemctl start 了一個
  • 舊服務器和新服務器同時在跑
  • 手動 openclaw gateway 和後臺 daemon 同時存在
修復： 
# 1. 殺掉所有 OpenClaw 進程

pkill -9 -f openclaw-gateway



2. 等 30 秒讓 Telegram API 釋放連接


sleep 30



3. 只啓動一個實例


systemctl --user start openclaw-gateway
教訓： Telegram Bot API 的 long-polling 是獨佔式的，全球只允許一個連接。遷移服務器時一定要先把舊的停掉！

🐛 Bug #4：Bot "假活" —— 無聲卡死 (Silent Hanging)

症狀： openclaw gateway status 顯示 Running，但 Bot 完全不響應消息。日誌文件最後更新時間停在幾小時前。 根因：

Telegram 的 long-polling 連接超時後沒有觸發錯誤，OpenClaw 以爲還在正常工作，但實際上已經收不到消息了。這是長連接服務的經典問題。

修復：

寫了���個 crontab watchdog，每 2 分鐘檢查日誌文件大小是否增長：

#!/bin/bash

/root/oc-watchdog.sh



LOG="/tmp/openclaw/openclaw-$(date +%Y-%m-%d).log"


MARKER="/tmp/oc-lastsize"



CURRENT=$(wc -c < "$LOG" 2>/dev/null || echo 0)


LAST=$(cat "$MARKER" 2>/dev/null || echo 0)



if [ "$CURRENT" = "$LAST" ] && [ "$LAST" != "0" ]; then


echo "$(date): bot log stale, restarting" >> /tmp/oc-watchdog.log


export XDG_RUNTIME_DIR=/run/user/0


export DBUS_SESSION_BUS_ADDRESS=unix:path=/run/user/0/bus


systemctl --user restart openclaw-gateway


fi



echo "$CURRENT" > "$MARKER"
# crontab -e

*/2 * * * * /root/oc-watchdog.sh
教訓： 長連接服務必須有外部健康檢查，不能只靠進程存活狀態判斷。日誌是否在增長是最簡單有效的健康指標。

🐛 Bug #5：Discord Bot 無法讀取消息內容

症狀：

Discord Bot 在線，能看到消息，但所有消息內容都是空的，AI 無法回覆。

根因：

Discord 2023 年起要求 Bot 必須開啓 Privileged Gateway Intents（特權網關意圖），特別是 Message Content Intent。不開的話 Bot 收到的消息 content 全是空字符串。

修復：
  • 去 Discord Developer Portal → 選你的 App → Bot
  • 開啓所有三個 Privileged Gateway Intents：

- ✅ Message Content Intent

- ✅ Server Members Intent

- ✅ Presence Intent

另外，Discord 的配置結構和 Telegram 不同，必須用 accounts.default.token 而不是直接放 botToken：

"discord": {

"enabled": true,


"accounts": {


"default": {


"token": "YOUR_DISCORD_BOT_TOKEN"


}


}


}
教訓： Discord 的 API 權限模型比 Telegram 複雜得多，一定要檢查 Intents 設置。

3. Claude Relay Service (CRS) 中轉服務篇

🐛 Bug #6：CRS 500 Internal Server Error (zstd 壓縮炸彈)

症狀：

通過中轉服務調用 Claude API 時，隨機出現 500 Internal Server Error，直連 Anthropic 沒問題。

根因：

CRS v1.1.279 及更早版本會把客戶端的 accept-encoding: zstd 直接透傳給上游 Anthropic API。當上遊返回 zstd 壓縮的響應時，CRS 自己解析不了，JSON 解析失敗，返回 500。

修復： 
cd ~/claude-relay-service

git pull


docker-compose pull


docker-compose up -d

升級到 v1.1.290+，這個版本包含了 commit f0b21fdc，會攔截 zstd 透傳。

教訓： 中轉服務一定要及時更新。壓縮編碼問題非常隱蔽——你在日誌裏只看到 500，根本想不到是 zstd 導致的。

4. Anthropic SDK 底層 Bug 篇

🐛 Bug #7：SSE 流中斷導致 Agent 崩潰 (我們提了 PR！🎉)

症狀：

OpenClaw 在處理長對話時隨機崩潰，錯誤信息：

AnthropicError: Unexpected event order, got message_start before receiving "message_stop"
根因：

這是 Anthropic SDK 的一個硬傷。當中轉服務（如 CRS）在上游中斷後��新傳輸 SSE 流時，SDK 會收到一個新的 message_start 事件，但舊的流還沒發 message_stop。SDK 的默認行爲是直接 throw，導致整個 Agent 運行崩潰。

修復：

我們寫了一個 patch 文件，修改 SDK 的 MessageStream.mjs：

- throw new AnthropicError(Unexpected event order, got ${event.type} before receiving "message_stop");

+ // 中轉/代理重傳時可能收到重複的 message_start，


+ // 不要崩潰，丟棄舊的不完整消息，從新消息重新開始


+ __classPrivateFieldSet(this, _MessageStream_currentMessageSnapshot, undefined, "f");


+ return event.message;



    

  • throw new AnthropicError(Unexpected event order, got ${event.type} before "message_start");
    • 



+ // 靜默忽略上一個（中斷的）流的殘留事件


+ return undefined;
教訓：
  • SDK 的異常處理不應該直接崩潰，特別是在有中轉層的場景下
  • 這個 bug 我們已經提了 PR 給 Anthropic，希望能合併
  • Patch 文件保存在 patches/anthropic-sdk-sse-resilience.patch
已經提交社區了 ↑ 開心 🎉

5. Telegram / Discord 集成篇

🐛 Bug #8：Telegram Bot 配對後仍無法響應

症狀：

Bot 配對成功（openclaw pairing approve 通過），但發消息無回覆。

根因：

多種可能：

  • allowFrom 白名單沒有加你的 Telegram User ID
  • groupPolicy 設爲 allowlist 但沒有配羣組 ID
  • Gateway 沒有重啓導致配置未生效
修復： 
# 確保你的 ID 在白名單裏

openclaw config set channels.telegram.allowFrom '["YOUR_TG_USER_ID"]'



重啓 Gateway


systemctl --user restart openclaw-gateway

快速排查清單

遇到問題時，按以下順序排查：

步驟檢查項命令
1Node.js 版本node --version
2IPv6 問題export NODE_OPTIONS="--dns-result-order=ipv4first"
3進程衝突ps aux \grep openclaw
4日誌是否增長ls -la /tmp/openclaw/
5Telegram 409殺掉所有進程，等 30 秒，重啓
6Discord Intents檢查 Developer Portal 權限
7CRS 版本docker-compose pull && docker-compose up -d
8白名單配置openclaw config get channels.telegram.allowFrom

還是解決不了？

如果以上方案都無法解決你的問題：

  • 聯繫管理員

- Telegram: @zhoumo_828

- 微信: Moumlbius

  • 提供以下信息

- 操作系統版本

- Node.js 版本

- 完整的錯誤信息

- 已嘗試的解決方案

作者： 小周 & Opus 4.8 發佈時間： 2026-03-14 字數： 3,247 字 閱讀時間： 約 12 分鐘 PS. 這篇文章會持續更新，遇到新坑就加進來。歡迎在留言區分享你的踩坑經歷！

🚀 Try youragent Now

Official 1:1 rate, only 4% of official price. Supports Cursor, VS Code, Claude Code and more.

Contact Admin for API Key