OpenClaw 避坑指南：新手最容易犯的 10 个错误

OpenClaw 避坑指南：新手最容易犯的 10 个错误

这篇文章来自真实的踩坑经历，每一条都是有代价的教训。如果你刚开始接触 OpenClaw，建议通读一遍再动手。

---

坑 1：直接用 root 用户运行 Docker

错误现象：部署成功，但几天后发现文件权限混乱，容器内生成的文件在宿主机无法删除。

原因：root 运行 Docker 会导致容器内文件以 root 权限写入挂载卷。

正确做法：

# 创建专用用户
sudo useradd -m -s /bin/bash openclaw
sudo usermod -aG docker openclaw

# 切换到该用户操作
su - openclaw

---

坑 2：不加 restart: unless-stopped 策略

错误现象：服务器重启后，OpenClaw 服务没有自动拉起，用户投诉系统宕机。

修复：

# docker-compose.yml 每个服务都要加
services:
  api:
    restart: unless-stopped
  worker:
    restart: unless-stopped
  postgres:
    restart: unless-stopped
  redis:
    restart: unless-stopped

---

坑 3：SECRET_KEY 使用默认值

错误现象：系统正常运行，但某天被提示账号遭到未授权访问。

原因：.env.example 中的 SECRET_KEY=changeme 被照搬到生产环境，攻击者可以伪造 JWT token。

修复：

# 生成真正随机的密钥
python3 -c "import secrets; print(secrets.token_hex(32))"
# 或
openssl rand -hex 32

这条错误可能导致严重安全事故，务必重视。

---

坑 4：不配置日志轮转导致磁盘打满

错误现象：某天凌晨收到磁盘告警，API 服务宕机，日志文件达到 40GB+。

原因：Docker 容器默认无限写入日志。

修复：

// /etc/docker/daemon.json
{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "100m",
    "max-file": "3"
  }
}

sudo systemctl daemon-reload && sudo systemctl restart docker

---

坑 5：数据库没有定期备份

错误现象：误操作删除了一批 Agent 配置，无法恢复，损失大量人工配置工作。

最小备份方案：

#!/bin/bash
# backup.sh
DATE=$(date +%Y%m%d_%H%M%S)
docker compose exec -T postgres pg_dump \
  -U ${POSTGRES_USER} ${POSTGRES_DB} \
  > /backup/openclaw_${DATE}.sql

# 只保留最近 7 天
find /backup -name "openclaw_*.sql" -mtime +7 -delete

# 加入 crontab，每天凌晨 3 点执行
0 3 * * * /home/openclaw/backup.sh

---

坑 6：LLM API Key 硬编码在配置文件中

错误现象：团队成员不小心把配置文件推送到 GitHub，API Key 被盗用，产生大额账单。

正确做法：

# .gitignore 必须包含
.env
*.env
.env.local
.env.production

# 检查是否有敏感文件已被 git 追踪
git ls-files | grep -i ".env"
# 如果有输出，立即从 git 历史中删除
git rm --cached .env

---

坑 7：不给 Worker 设置内存限制

错误现象：某个异常的 Agent 任务触发了无限循环，Worker 内存不断增长，最终 OOM 导致整台服务器卡死。

修复：

services:
  worker:
    deploy:
      resources:
        limits:
          memory: 2G
        reservations:
          memory: 512M

---

坑 8：WebSocket 超时配置不完整

错误现象：对话进行到一半突然断开，前端显示"连接已断开"，长文本生成场景尤其明显。

原因：Nginx 默认 proxy_read_timeout 60s，长输出超过 60 秒就断连。

修复：

location / {
    proxy_read_timeout 300s;     # 必须显式设置
    proxy_send_timeout 300s;
    proxy_connect_timeout 10s;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
}

---

坑 9：升级前不看 CHANGELOG

错误现象：直接 docker pull 拉取 latest，升级后发现 API 接口有 Breaking Change，集成的业务系统全部报 500。

正确做法：

1. 永远使用固定版本号的镜像，如 openclaw/api:2.1.4
2. 升级前阅读 GitHub Releases 页面的迁移说明
3. 先在测试环境验证，再升级生产

---

坑 10：生产环境开启 DEBUG 模式

错误现象：系统报错时，页面直接返回详细的堆栈信息，包含数据库连接字符串等敏感信息。

修复：

# .env 生产环境必须设置
DEBUG=false
LOG_LEVEL=WARNING

---

总结

这 10 个坑覆盖了安全、稳定性、运维三个维度，每个都是真实发生过的事故。如果你希望从一开始就规避这些风险，LocalClaw（insman.cn） 上有经验丰富的 OpenClaw 服务商，可以提供包含最佳实践的部署交付，避免新手踩坑。