OpenClaw安装配置常见问题排查

OpenClaw 安装配置捉虫记录：真实踩坑 + 解决方案

2026-03-14·小周 & Opus 4.6

OpenClaw 安装配置捉虫记录：真实踩坑 + 解决方案

作者： 小周 & Opus 4.6 时间： 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 [email protected] "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.6 发布时间： 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.6 时间： 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 [email protected] "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.6 发布时间： 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