故障排查

本文档汇总 Gateway 运行中最常见的问题及其解决方案。

快速诊断

遇到问题时，先运行内置诊断工具：

bash

# 综合诊断
openclaw doctor

# 查看 Gateway 状态
openclaw status

# 查看实时日志
openclaw logs --follow --level error

常见问题

EADDRINUSE: 端口被占用

现象：

text

[ERROR] Failed to start gateway: listen EADDRINUSE: address already in use :::18789

原因：端口 18789 已被另一个进程占用。

解决方案：

查找占用进程 (Linux/macOS)查找占用进程 (Windows)

bash

# 查找占用端口的进程
lsof -i :18789

# 输出示例：
# COMMAND   PID   USER   FD   TYPE  DEVICE SIZE/OFF NODE NAME
# openclaw  42187 user   12u  IPv4  0x1234 0t0      TCP  *:18789

# 停止占用进程
kill 42187

bash

# 查找占用端口的进程
netstat -ano | findstr :18789

# 通过 PID 查找进程名
tasklist | findstr <PID>

# 终止进程
taskkill /PID <PID> /F

bash

# 或者使用其他端口
openclaw gateway --port 18790

已有 Gateway 实例

最常见的原因是已有一个 Gateway 实例在运行。使用 openclaw status 确认，并用 openclaw gateway stop 停止。

unauthorized: 认证失败

现象：

text

Connection failed: unauthorized — The provided token is invalid or expired.

排查步骤：

bash

# 1. 确认 Token 环境变量已设置
echo $OPENCLAW_GATEWAY_TOKEN

# 2. 确认 Token 非空
if [ -z "$OPENCLAW_GATEWAY_TOKEN" ]; then
  echo "Token is not set!"
fi

# 3. 检查 Gateway 端的认证配置
openclaw config get gateway.auth

# 4. 检查是否被速率限制
openclaw logs --filter "rate_limit"

常见原因：

原因	解决方案
Token 未设置	`export OPENCLAW_GATEWAY_TOKEN="your-token"`
Token 不匹配	确认客户端和 Gateway 使用相同 Token
速率限制	等待锁定时间过期（默认 60 秒）
Token 含特殊字符	用引号包裹 Token 值

连接中断 / 频繁断开

现象：

text

[WARN] WebSocket connection lost, reconnecting...
[ERROR] Reconnection failed after 5 attempts

排查步骤：

bash

# 1. 检查 Gateway 是否仍在运行
openclaw status

# 2. 检查网络连通性
curl http://127.0.0.1:18789/health

# 3. 检查 Gateway 日志
openclaw logs --filter "disconnect" --lines 50

# 4. 检查系统资源
openclaw doctor --check resources

常见原因与解决方案：

原因	解决方案
Gateway 进程崩溃	检查日志中的 crash 信息，重启 Gateway
内存不足 (OOM)	增加系统内存或减少 `maxSessions`
反向代理超时	增加 `proxy_read_timeout`（参阅远程访问）
网络不稳定	检查网络质量，考虑 Tailscale

Channel 连接失败

现象：

text

[ERROR] Channel "openai" connection failed: 401 Unauthorized
[ERROR] Channel "anthropic" connection failed: ETIMEDOUT

排查步骤：

bash

# 1. 检查 Channel 状态
openclaw status --detailed

# 2. 验证 API Key
openclaw doctor --check channels

# 3. 测试网络连通性
curl -I https://api.openai.com/v1/models \
  -H "Authorization: Bearer $OPENAI_API_KEY"

# 4. 检查代理设置
echo $HTTP_PROXY
echo $HTTPS_PROXY

错误	原因	解决方案
`401 Unauthorized`	API Key 无效	重新设置：`openclaw secrets set OPENAI_API_KEY "..."`
`403 Forbidden`	账户欠费或权限不足	检查 API 提供商账户
`ETIMEDOUT`	网络不通	检查防火墙和代理设置
`ECONNREFUSED`	本地模型服务未启动	启动 Ollama：`ollama serve`
`429 Rate Limited`	API 限速	等待或升级 API 配额

性能问题

现象：响应缓慢、高延迟、高 CPU/内存。

排查步骤：

bash

# 1. 查看资源使用
openclaw status --detailed

# 2. 检查活跃会话数
openclaw status | grep sessions

# 3. 查看慢请求
openclaw logs --filter "slow" --level warn

# 4. 检查 Channel 延迟
openclaw doctor --check channels

优化建议：

问题	优化方案
会话过多	减少 `maxSessions`，清理空闲会话
内存占用高	减少并发、清理历史会话
CPU 占用高	减少本地模型并发数
响应慢	检查 Channel 延迟，考虑使用更近的 API 端点

配置错误

现象：

text

[ERROR] Configuration validation failed:
  - channels[0].provider: unknown provider "gpt4"
  - models.default: model "gpt-5" not found in any channel

解决方案：

bash

# 验证配置文件
openclaw config validate

# 查看当前配置
openclaw config list

# 修复配置
openclaw config set channels[0].provider openai
openclaw config set models.default gpt-4o

锁文件问题

现象：

text

[ERROR] Another gateway instance is already running (PID: 98765)

但实际上没有 Gateway 在运行（异常退出后残留锁文件）。

bash

# 检查锁文件状态
openclaw gateway lock-info

# 如果是过期锁，手动清理
openclaw gateway unlock

详见网关锁。

日志分析

查找错误

bash

# 查看所有错误日志
openclaw logs --level error --lines 100

# 按时间范围过滤
openclaw logs --since "1 hour ago" --level error

# 按关键字搜索
openclaw logs --filter "timeout"

开启 Debug 日志

临时开启详细日志排查问题：

bash

# 动态调整日志级别
openclaw config set gateway.logLevel debug

# 排查完成后恢复
openclaw config set gateway.logLevel info

性能影响

Debug 日志会记录大量信息，排查完毕后务必恢复为 info 级别。

恢复程序

完全重置

当所有排查方法都无效时，可以尝试完全重置：

bash

# 1. 停止 Gateway
openclaw gateway stop --force

# 2. 清理锁文件
openclaw gateway unlock --force

# 3. 验证配置
openclaw config validate

# 4. 重新启动
openclaw gateway

# 5. 运行诊断
openclaw doctor

数据重置

如果上述步骤仍无法解决，可以备份后重置数据目录：

bash

# 备份
cp -r ~/.openclaw ~/.openclaw.backup

# 重置
rm -rf ~/.openclaw
openclaw gateway   # 会重新创建默认配置

获取帮助

如果以上方案都未能解决你的问题：

收集诊断信息：openclaw doctor --format json > doctor.json
收集日志：openclaw logs --lines 500 > gateway.log
在 GitHub Issues 提交问题

故障排查 ​

快速诊断 ​

常见问题 ​

EADDRINUSE: 端口被占用 ​

unauthorized: 认证失败 ​

连接中断 / 频繁断开 ​

Channel 连接失败 ​

性能问题 ​

配置错误 ​

锁文件问题 ​

日志分析 ​

查找错误 ​

开启 Debug 日志 ​

恢复程序 ​

完全重置 ​

获取帮助 ​

相关文档 ​

故障排查

快速诊断

常见问题

EADDRINUSE: 端口被占用

unauthorized: 认证失败

连接中断 / 频繁断开

Channel 连接失败

性能问题

配置错误

锁文件问题

日志分析

查找错误

开启 Debug 日志

恢复程序

完全重置

获取帮助

相关文档