OpenClaw常见错误解决方案

OpenClaw常见错误解决方案摘要本文档总结了OpenClaw使用中常见的三类问题及解决方法。

兰溪辰

1736人浏览 · 2026-03-21 15:22:24

兰溪辰 · 2026-03-21 15:22:24 发布

OpenClaw常见错误解决方案

本文档基于常见的OpenClaw 遇到的各类常见错误及解决方案。

1. 文件权限问题

1.1 Config 文件权限问题

错误描述：

EACCES: permission denied, open '/home/user/.openclaw/config.yaml'
配置更改后无法保存
启动时无法读取配置文件
Error: Cannot parse config file

可能原因：

配置文件被 root 用户创建，当前用户无读取权限
多用户系统中，配置文件权限设置为 600，其他用户无法访问
配置文件所在目录缺少执行权限（无法进入目录）
SELinux/AppArmor 限制了文件访问
配置文件被其他进程锁定
磁盘挂载为只读模式（如系统恢复模式）

解决思路：

# 检查文件权限
ls -la ~/.openclaw/config.yaml

# 修复权限（确保当前用户可读写）
chmod 644 ~/.openclaw/config.yaml
chown $(whoami):$(whoami) ~/.openclaw/config.yaml

# 检查目录权限
ls -ld ~/.openclaw/
chmod 755 ~/.openclaw/

# 检查 SELinux 状态
getenforce
ls -Z ~/.openclaw/config.yaml

# 检查磁盘挂载状态
mount | grep "on / "

1.2 日志文件权限问题

错误描述：

Error: EACCES: permission denied, open '/var/log/openclaw/app.log'
日志轮转后无法创建新日志文件
日志写入失败导致应用崩溃
磁盘空间充足但无法写入日志

可能原因：

日志目录权限不足
以非 root 用户运行但日志目录需要 root 权限
日志文件被 root 创建，应用以普通用户运行
日志目录的父目录缺少执行权限
日志文件系统已满或达到 inode 限制
logrotate 配置不当导致权限问题

解决思路：

# 创建专用日志目录并设置权限
sudo mkdir -p /var/log/openclaw
sudo chown -R openclaw:openclaw /var/log/openclaw
sudo chmod 755 /var/log/openclaw

# 或使用用户目录存放日志
mkdir -p ~/.openclaw/logs

# 检查 inode 使用情况
df -i /var/log

# 配置 logrotate
sudo tee /etc/logrotate.d/openclaw << 'EOF'
/var/log/openclaw/*.log {
    daily
    rotate 14
    compress
    delaycompress
    missingok
    notifempty
    create 0644 openclaw openclaw
    sharedscripts
}
EOF

1.3 数据目录权限问题

错误描述：

Error: EACCES: permission denied, mkdir '/var/lib/openclaw/data'
数据库文件锁定错误
SQLite: database is locked
无法创建 PID 文件

可能原因：

数据目录需要初始化权限
多实例同时访问同一数据目录
数据文件被其他进程占用
NFS/SMB 共享目录的锁机制问题
数据目录跨用户访问权限问题

解决思路：

# 创建数据目录并设置正确权限
sudo mkdir -p /var/lib/openclaw
sudo chown -R openclaw:openclaw /var/lib/openclaw
sudo chmod 750 /var/lib/openclaw

# 检查文件锁定
lsof ~/.openclaw/data/db.sqlite
fuser ~/.openclaw/data/db.sqlite

# 对于 SQLite，确保单进程访问或使用 WAL 模式
# 在配置中启用 WAL 模式
PRAGMA journal_mode=WAL;

# NFS 共享目录问题
# 使用本地目录或配置正确的锁机制

1.4 Socket 文件权限问题

错误描述：

Error: listen EACCES: permission denied /var/run/openclaw.sock
Unix Socket 连接被拒绝
客户端无法连接到服务端 Socket

可能原因：

Socket 文件权限过于严格
运行用户与创建用户不一致
/var/run 目录在重启后被清理
Socket 目录权限不足

解决思路：

# 创建专用运行时目录
sudo mkdir -p /var/run/openclaw
sudo chown openclaw:openclaw /var/run/openclaw

# 或使用 systemd RuntimeDirectory
# 在 service 文件中添加：
# RuntimeDirectory=openclaw

# 设置 umask 确保 Socket 文件权限正确
umask 0002

# 配置 Socket 权限
chmod 660 /var/run/openclaw.sock

2. 内存和资源限制问题

2.1 内存不足 (OOM)

错误描述：

FATAL ERROR: Reached heap limit Allocation failed - JavaScript heap out of memory
Error: spawn ENOMEM
进程被系统 OOM killer 终止
响应缓慢，频繁 GC

可能原因：

Node.js 默认堆内存限制（约 1.4GB for 64bit）
大量并发连接导致内存增长
内存泄漏（未关闭的连接、事件监听器累积）
大文件处理或缓冲区未释放
系统物理内存不足
容器内存限制（cgroups）

解决思路：

# 增加 Node.js 堆内存限制
node --max-old-space-size=4096 /usr/bin/openclaw

# 在 systemd 服务中设置
[Service]
Environment="NODE_OPTIONS=--max-old-space-size=4096"
MemoryMax=8G
MemorySwapMax=0

# 监控内存使用
# 启用 heap dump 分析
node --heapsnapshot-near-heap-limit=3 app.js

# 检查内存泄漏
# 使用 clinic.js 或 node --inspect

2.2 文件描述符限制

错误描述：

Error: EMFILE: too many open files
Error: ENFILE: file table overflow
无法接受新连接
随机文件操作失败

可能原因：

默认 ulimit 限制（通常 1024）
大量并发 WebSocket 连接
文件句柄未正确关闭
连接泄漏
系统级 fs.file-max 限制

解决思路：

# 查看当前限制
ulimit -n
cat /proc/sys/fs/file-max

# 临时增加限制
ulimit -n 65536

# 永久设置（/etc/security/limits.conf）
openclaw soft nofile 65536
openclaw hard nofile 65536

# systemd 服务设置
[Service]
LimitNOFILE=65536

# 系统级设置
# /etc/sysctl.conf
fs.file-max = 2097152

# 代码层面确保关闭句柄
# 使用 graceful-fs 处理 EMFILE

2.3 CPU 限制和性能问题

错误描述：

响应延迟高
事件循环阻塞警告
Warning: Event loop blocked for X ms
CPU 使用率 100%

可能原因：

同步操作阻塞事件循环
大量计算任务在主线程执行
正则表达式灾难性回溯
JSON 解析大对象
加密/解密操作过于频繁

解决思路：

// 使用 worker_threads 处理 CPU 密集型任务
const { Worker } = require('worker_threads');

// 使用 setImmediate 让出事件循环
setImmediate(() => {
  // 处理下一个批次
});

// 使用 stream 处理大文件
const stream = fs.createReadStream('large-file.json');

2.4 磁盘空间问题

错误描述：

Error: ENOSPC: no space left on device
日志写入失败
数据库操作失败
临时文件创建失败

可能原因：

日志文件过大
临时文件未清理
数据库文件增长
核心转储文件累积

解决思路：

# 检查磁盘空间
df -h
du -sh ~/.openclaw/*

# 清理日志
find ~/.openclaw/logs -name "*.log" -mtime +30 -delete

# 配置日志轮转
# 限制核心转储大小
ulimit -c 0

# 监控磁盘使用
# 设置告警阈值

3. 系统服务相关问题（systemd）

3.1 服务启动失败

错误描述：

Failed to start OpenClaw Gateway
Main process exited, code=exited, status=203/EXEC
服务状态为 failed
启动后立即退出

可能原因：

ExecStart 路径错误
Node.js 未找到或版本不匹配
环境变量缺失
工作目录不存在
权限不足

解决思路：

# 检查服务状态
systemctl status openclaw-gateway

# 查看详细日志
journalctl -u openclaw-gateway -n 100 --no-pager

# 验证路径
which node
ls -la /usr/bin/openclaw

# 测试手动启动
sudo -u openclaw /usr/bin/node /usr/lib/openclaw/dist/index.js

# 检查环境变量
systemctl show-environment

3.2 服务重启循环

错误描述：

服务不断重启
Start request repeated too quickly
达到 StartLimitInterval 限制

可能原因：

配置错误导致启动即崩溃
依赖服务未启动
端口被占用
数据库连接失败

解决思路：

# 停止重启循环
systemctl stop openclaw-gateway

# 查看失败原因
journalctl -u openclaw-gateway -f

# 增加重启延迟和限制
[Service]
Restart=on-failure
RestartSec=5
StartLimitInterval=60s
StartLimitBurst=3

# 检查依赖
[Unit]
After=network.target postgresql.service
Wants=network-online.target

3.3 权限和沙箱问题

错误描述：

Failed to determine user credentials: No such process
Permission denied 在沙箱环境中
无法访问某些系统调用

可能原因：

User= 设置的用户不存在
沙箱限制（PrivateTmp, ProtectSystem 等）
Capability 设置不当
SELinux 阻止操作

解决思路：

[Service]
# 确保用户存在
User=openclaw
Group=openclaw

# 调整沙箱设置
PrivateTmp=yes
ProtectSystem=strict
ProtectHome=yes
ReadWritePaths=/var/lib/openclaw /var/log/openclaw

# 添加必要的能力
AmbientCapabilities=CAP_NET_BIND_SERVICE

# 或禁用某些限制进行调试
# PrivateTmp=no
# ProtectSystem=no

3.4 日志和日志轮转问题

错误描述：

日志未写入 journal
日志丢失
journal 占用过多磁盘空间

解决思路：

[Service]
# 确保日志输出到 journal
StandardOutput=journal
StandardError=journal
SyslogIdentifier=openclaw

# 调试级别日志
Environment="DEBUG=*"
Environment="LOG_LEVEL=debug"

# 配置 journal 持久化
sudo mkdir -p /var/log/journal
sudo systemd-tmpfiles --create --prefix /var/log/journal

# 限制 journal 大小
# /etc/systemd/journald.conf
[Journal]
SystemMaxUse=500M
SystemMaxFileSize=100M

4. 网络代理和防火墙问题

4.1 绑定地址/端口失败

错误描述：

Error: listen EADDRINUSE: address already in use :::8080
Error: listen EACCES: permission denied 0.0.0.0:80
Error: listen EADDRNOTAVAIL: invalid address

可能原因：

端口已被其他进程占用
低于 1024 的端口需要特权
绑定的 IP 地址不存在
端口处于 TIME_WAIT 状态

解决思路：

# 查找占用端口的进程
sudo lsof -i :8080
sudo ss -tlnp | grep 8080

# 释放端口
sudo kill -9 <PID>

# 或使用特权端口方案
# 1. 使用 authbind
# 2. 使用 setcap
capsh --print | grep cap_net_bind_service

# 3. 使用 higher port + 反向代理
# 配置 nginx/haproxy 转发

# 配置 SO_REUSEADDR

4.2 防火墙阻止连接

错误描述：

外部无法访问服务
连接超时
特定端口无法访问
WebSocket 连接失败

可能原因：

iptables/nftables 规则阻止
ufw/firewalld 未开放端口
云服务商安全组限制
Docker 网络隔离

解决思路：

# 检查防火墙状态
sudo ufw status
sudo firewall-cmd --list-all
sudo iptables -L -n | grep DROP

# 开放端口
sudo ufw allow 8080/tcp
sudo firewall-cmd --permanent --add-port=8080/tcp
sudo firewall-cmd --reload

# 检查云安全组
# AWS: Security Groups
# Azure: Network Security Groups
# GCP: Firewall Rules

# 测试端口连通性
nc -zv <host> <port>
telnet <host> <port>

4.3 代理服务器问题

错误描述：

无法访问外部 API
连接通过代理失败
SSL/TLS 握手失败通过代理
WebSocket 通过 HTTP 代理失败

可能原因：

HTTP_PROXY/HTTPS_PROXY 环境变量未设置
代理需要认证
代理不支持 WebSocket CONNECT 方法
代理 SSL 检查干扰连接

解决思路：

# 设置代理环境变量
export HTTP_PROXY=http://proxy.company.com:8080
export HTTPS_PROXY=http://proxy.company.com:8080
export NO_PROXY=localhost,127.0.0.1,.local

# 在 systemd 服务中设置
[Service]
Environment="HTTP_PROXY=http://proxy:8080"
Environment="NO_PROXY=localhost,127.0.0.1"

# Node.js 代理配置
# 使用 https-proxy-agent 或 proxy-agent

4.4 WebSocket 特定问题

错误描述：

WebSocket connection failed: Error in connection establishment
Error: Unexpected server response: 400
WebSocket 握手失败
连接频繁断开

可能原因：

反向代理未配置 WebSocket 支持
负载均衡器超时设置过短
Nginx proxy_read_timeout 过短
企业防火墙阻止 WebSocket

解决思路：

# Nginx WebSocket 配置
location /ws {
    proxy_pass http://backend;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    
    # 延长超时
    proxy_read_timeout 86400;
    proxy_send_timeout 86400;
}

5. 时区和时间同步问题

5.1 时间不同步问题

错误描述：

SSL/TLS 证书验证失败（时间相关）
JWT token 验证失败（expired）
日志时间戳不一致
定时任务执行时间错误

可能原因：

系统时间未同步
时区设置错误
NTP 服务未运行
硬件时钟（RTC）漂移

解决思路：

# 检查时区
timedatectl status
cat /etc/timezone

# 设置时区
sudo timedatectl set-timezone Asia/Shanghai

# 启用 NTP 同步
sudo timedatectl set-ntp true

# 检查 NTP 状态
systemctl status systemd-timesyncd
# 或使用 chrony
chronyc tracking

# 强制时间同步
sudo ntpdate -s time.nist.gov

5.2 容器时区问题

错误描述：

容器内时间戳与主机不一致
日志时间戳混乱
定时任务在错误时间执行

解决思路：

# Dockerfile 中设置时区
RUN ln -sf /usr/share/zoneinfo/Asia/Shanghai /etc/localtime \
    && echo "Asia/Shanghai" > /etc/timezone

# 运行容器时挂载时区
docker run -v /etc/localtime:/etc/localtime:ro ...

# 或使用 TZ 环境变量
docker run -e TZ=Asia/Shanghai ...

6. SSL/TLS 证书问题

6.1 证书文件问题

错误描述：

Error: ENOENT: no such file or directory, open '/etc/openclaw/ssl/cert.pem'
Error: error:0909006C:PEM routines:get_name:no start line
Error: error:0908F066:PEM routines:get_header_and_data:bad end line
证书格式错误

可能原因：

证书路径配置错误
证书文件权限不足
证书格式不正确（如包含 BOM）
证书链不完整

解决思路：

# 验证证书文件
openssl x509 -in cert.pem -text -noout
openssl rsa -in key.pem -check

# 检查证书链完整性
openssl verify -CAfile ca.pem cert.pem

# 检查文件权限
ls -la /etc/openclaw/ssl/
chmod 644 cert.pem
chmod 600 key.pem

# 转换证书格式
openssl x509 -in cert.crt -out cert.pem -outform PEM

6.2 证书过期和续期

错误描述：

Error: certificate has expired
浏览器显示证书不安全
客户端拒绝连接

可能原因：

Let’s Encrypt 证书 90 天过期
自动续期失败
时钟不同步导致误判

解决思路：

# 检查证书过期时间
openssl x509 -in cert.pem -noout -dates

# 使用 certbot 自动续期
sudo certbot renew --dry-run

# 配置自动续期钩子
# /etc/letsencrypt/renewal-hooks/deploy/restart-openclaw
#!/bin/bash
systemctl restart openclaw-gateway

# 监控证书过期
# 设置 30 天过期告警

6.3 TLS 版本和密码套件问题

错误描述：

Error: write EPROTO ... wrong version number
旧客户端无法连接
安全扫描报告弱加密

解决思路：

// Node.js TLS 配置
const tlsOptions = {
  minVersion: 'TLSv1.2',
  maxVersion: 'TLSv1.3',
  cipherSuites: 'TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256',
  honorCipherOrder: true
};

6.4 自签名证书和 CA 信任

错误描述：

Error: unable to verify the first certificate
Error: self signed certificate
客户端拒绝自签名证书

解决思路：

# 添加自签名证书到系统信任库
sudo cp ca-cert.pem /usr/local/share/ca-certificates/
sudo update-ca-certificates

# Node.js 特定（仅开发环境）
export NODE_TLS_REJECT_UNAUTHORIZED=0
# 或
NODE_EXTRA_CA_CERTS=/path/to/ca-cert.pem

7. 数据库/存储问题

7.1 SQLite 数据库问题

错误描述：

SQLITE_BUSY: database is locked
SQLITE_CORRUPT: database disk image is malformed
SQLITE_READONLY: attempt to write a readonly database
SQLITE_CANTOPEN: unable to open database file

可能原因：

多进程同时写入
事务未正确提交/回滚
磁盘空间不足
数据库文件损坏
网络文件系统（NFS）上的锁问题

解决思路：

-- 启用 WAL 模式减少锁竞争
PRAGMA journal_mode=WAL;
PRAGMA synchronous=NORMAL;

-- 增加 busy timeout
PRAGMA busy_timeout=5000;

# 修复损坏的数据库
sqlite3 db.sqlite ".dump" | sqlite3 db_fixed.sqlite
mv db_fixed.sqlite db.sqlite

# 检查数据库完整性
sqlite3 db.sqlite "PRAGMA integrity_check;"

7.2 连接池耗尽

错误描述：

Error: Timeout acquiring a connection
Error: Too many connections
数据库响应缓慢

可能原因：

连接未正确释放
连接池配置过小
长时间运行的查询占用连接
连接泄漏

解决思路：

// 配置连接池
const dbConfig = {
  pool: {
    min: 2,
    max: 20,
    acquireTimeoutMillis: 30000,
    idleTimeoutMillis: 30000
  }
};

// 确保使用 try/finally 释放连接

7.3 存储后端问题

错误描述：

数据持久化失败
存储后端连接超时
数据不一致

可能原因：

Redis/MongoDB/PostgreSQL 连接问题
存储后端资源不足
网络分区
主从复制延迟

解决思路：

# 检查存储后端状态
redis-cli ping
mongosh --eval "db.adminCommand('ping')"

# 监控复制延迟
# 配置连接重试和超时

8. 升级和迁移问题

8.1 版本升级失败

错误描述：

升级后无法启动
配置格式不兼容
数据库 schema 不匹配
依赖版本冲突

可能原因：

破坏性变更未处理
配置文件格式更新
Node.js 版本不兼容
原生模块需要重新编译

解决思路：

# 备份当前配置和数据
cp -r ~/.openclaw ~/.openclaw.backup.$(date +%Y%m%d)

# 查看升级说明
cat UPGRADE.md

# 逐步升级（不要跨大版本）
# 1.x -> 2.x -> 3.x

# 重新安装依赖
rm -rf node_modules
npm ci

# 运行数据库迁移
npx openclaw migrate

# 测试配置
openclaw config validate

8.2 数据迁移问题

错误描述：

迁移脚本失败
数据丢失
新旧数据格式不兼容

解决思路：

# 备份数据库
sqlite3 data.db ".backup data.db.backup"

# 测试迁移
openclaw migrate --dry-run

# 回滚迁移
openclaw migrate rollback

# 手动修复
sqlite3 data.db < fix-migration.sql

8.3 配置迁移

错误描述：

新配置选项缺失
旧配置选项被弃用警告
配置验证失败

解决思路：

# 生成新配置模板
openclaw config init --template

# 对比新旧配置
diff config.old.yaml config.new.yaml

# 自动迁移配置
openclaw config migrate

9. 多用户/权限问题

9.1 用户隔离问题

错误描述：

用户 A 看到用户 B 的数据
权限提升漏洞
无法访问共享资源

可能原因：

权限检查缺失
会话混淆
资源 ID 可猜测
水平/垂直权限绕过

解决思路：

// 实施严格的权限检查
async function getResource(userId, resourceId) {
  const resource = await db.query(
    'SELECT * FROM resources WHERE id = ? AND owner_id = ?',
    [resourceId, userId]
  );
  if (!resource) throw new ForbiddenError();
  return resource;
}

9.2 组权限问题

错误描述：

组成员权限不生效
权限变更后未立即生效
嵌套组权限复杂

解决思路：

# 检查用户组
id username
groups username

# 刷新组信息（不重新登录）
newgrp groupname

# 检查 ACL
getfacl /path/to/resource

9.3 sudo 和特权提升

错误描述：

sudo 命令失败
特权操作被拒绝
sudo 密码提示频繁

解决思路：

# 配置 sudoers
# /etc/sudoers.d/openclaw
openclaw ALL=(root) NOPASSWD: /usr/bin/systemctl restart openclaw-gateway

# 检查 sudo 权限
sudo -l -U openclaw

10. 容器/Podman 部署问题

10.1 镜像构建问题

错误描述：

docker build 失败
镜像体积过大
构建缓存问题
多架构构建失败

解决思路：

# 使用多阶段构建减少镜像大小
FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production

FROM node:20-alpine
WORKDIR /app
COPY --from=builder /app/node_modules ./node_modules
COPY . .
USER node
EXPOSE 8080
CMD ["node", "index.js"]

# 清理构建缓存
docker builder prune

# 多架构构建
docker buildx create --use
docker buildx build --platform linux/amd64,linux/arm64 -t openclaw:latest .

10.2 容器运行时问题

错误描述：

容器立即退出
健康检查失败
资源限制导致 OOM
权限不足

解决思路：

# 查看容器日志
docker logs container_id

# 以调试模式运行
docker run -it --entrypoint /bin/sh openclaw:latest

# 调整资源限制
docker run -m 512m --cpus=1.0 openclaw:latest

# 以 root 调试权限问题
docker run -u root openclaw:latest

10.3 网络问题

错误描述：

容器间无法通信
无法访问外部网络
端口映射失败
DNS 解析失败

解决思路：

# 检查网络配置
docker network ls
docker network inspect bridge

# 使用自定义网络
docker network create openclaw-net
docker run --network openclaw-net --name gateway openclaw:latest

# 检查 DNS
docker run --rm openclaw:latest nslookup google.com

# 端口映射
docker run -p 0.0.0.0:8080:8080 openclaw:latest

10.4 存储和卷问题

错误描述：

数据在容器重启后丢失
卷权限错误
绑定挂载失败
存储性能问题

解决思路：

# 使用命名卷
docker volume create openclaw-data
docker run -v openclaw-data:/data openclaw:latest

# 修复卷权限
docker run --rm -v openclaw-data:/data busybox chown -R 1000:1000 /data

# 绑定挂载时设置正确权限
docker run -v $(pwd)/data:/data:Z openclaw:latest  # :Z for SELinux

# 使用卷驱动
docker volume create --driver local \
  --opt type=nfs \
  --opt o=addr=192.168.1.100,rw \
  --opt device=:/path/to/share \
  openclaw-nfs

10.5 Podman 特定问题

错误描述：

rootless 容器权限问题
端口绑定失败（<1024）
与 Docker 的行为差异

解决思路：

# rootless 容器绑定特权端口
sysctl net.ipv4.ip_unprivileged_port_start=80

# 或使用 rootful 容器
sudo podman run ...

# 检查用户命名空间
podman unshare cat /proc/self/uid_map

# 生成 systemd 服务
podman generate systemd --new --name openclaw-gateway

10.6 Docker Compose 问题

错误描述：

服务启动顺序问题
环境变量未传递
网络隔离问题
卷数据不共享

解决思路：

# docker-compose.yml
version: '3.8'
services:
  gateway:
    image: openclaw:latest
    depends_on:
      redis:
        condition: service_healthy
    environment:
      - REDIS_URL=redis://redis:6379
    volumes:
      - ./config:/config:ro
      - data:/data
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
      interval: 30s
      timeout: 10s
      retries: 3

  redis:
    image: redis:7-alpine
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]

volumes:
  data:

附录：诊断工具速查

系统诊断

# 系统信息
uname -a
lsb_release -a
cat /etc/os-release

# 资源使用
top/htop
free -h
df -h
iostat -x 1

# 网络诊断
ss -tlnp
netstat -tlnp
lsof -i
tcpdump -i any port 8080

Node.js 诊断

# 进程信息
ps aux | grep node
pgrep -a node

# 调试
node --inspect index.js
node --prof index.js

# 内存分析
node --heapsnapshot-near-heap-limit=3 index.js

日志分析

# 实时日志
journalctl -u openclaw-gateway -f
tail -f /var/log/openclaw/app.log

# 日志搜索
journalctl -u openclaw-gateway --since "1 hour ago" | grep ERROR
grep -r "error" /var/log/openclaw/

实际场景错误补充

家庭场景特有问题

路由器重启后的连接问题

错误现象：

Gateway unreachable: ECONNREFUSED 192.168.1.100:18789

根本原因：路由器重启后 DHCP 重新分配 IP，原书签失效
场景特点：家庭网络中很常见，用户不明白为什么昨天还能访问
快速修复：

# 使用 mDNS 避免 IP 变化影响
openclaw config set gateway.advertiseLocalDomain true
# 访问 http://openclaw-local.local:18789

家人设备配对困惑

错误现象：

Pairing required for device "iPhone-Mom" (req_abc123)

用户行为：家人不知道什么是 “requestId”，怎么批准
场景优化：

# 家庭环境简化命令
openclaw devices approve-latest --alias "妈妈的手机"
# 自动批准最近一个请求并设置友好名称

办公环境特有问题

企业代理导致的连接失败

错误现象：

Proxy error: ECONNREFUSED proxy.company.com:8080
WebSocket handshake failed (407 Proxy Authentication Required)

企业特点：必须走代理，还需要域名认证
解决方案：

// 企业环境下的代理配置
const proxyConfig = {
  http_proxy: 'http://domain\\username:password@proxy.company.com:8080',
  https_proxy: 'http://domain\\username:password@proxy.company.com:8080',
  no_proxy: 'localhost,127.0.0.1,.local,.company.com'
};

组策略阻止执行

错误现象：

System policy prevents execution: Software Restriction Policy

企业特点：IT 部门通过组策略限制可执行程序
绕过方案：

# 申请白名单
# 或者使用便携模式（不需要安装）
openclaw config set exec.mode "portable"

远程访问场景问题

Tailscale 中继模式高延迟

错误现象：

WebSocket connection lag: 800ms (via relay)
Direct connection failed, falling back to DERP

用户感受：连接能用但很卡，不明白为什么
诊断命令：

tailscale ping <device-name>  # 看是否直连
tailscale netcheck           # 检查 NAT 类型

公共 WiFi 的端口封锁

错误现象：

Connection timeout: ECONNREFUSED (port 18789)

场景特点：酒店、咖啡厅的 WiFi 会封锁非常用端口
应对方案：

# 使用常见端口
openclaw config set gateway.port 443  # HTTPS 端口通常开放
# 或者 80, 8080, 8443 等

升级维护场景问题

配置格式不兼容的静默失败

错误现象：

Config warning: unknown option 'oldFeature'
Gateway starting with partial configuration...

用户痛点：没有立即报错，但功能不正常，很难排查
改进建议：

# 升级前检查
openclaw config validate --strict  # 严格模式检查未知选项
openclaw migrate preview          # 预览需要迁移的内容

Docker 容器重启丢数据

错误现象：

Error: ENOENT: no such file or directory, open '/data/config.json'

根本原因：用户没用 volume，容器重启数据丢失
场景教育：

# 正确的 Docker 使用方式
docker run -v openclaw-data:/data \
           -v openclaw-config:/config \
           openclaw/openclaw:latest

用户行为模式分析

典型错误处理流程

遇到问题 → 重复尝试（点刷新、重连）
无效后 → 搜索错误信息（找到零散解决方案）
盲目尝试 → 可能解决/可能更糟
寻求帮助 → 提供不完整信息

改进的交互设计

# 智能错误提示（理想情况）
Error: Connection refused to 192.168.1.100:18789
Suggestion: This IP looks like a home router address. 
          Try: openclaw config set gateway.bind "lan"
          Or access via: http://$(hostname).local:18789