OpenClaw 跑不起来？20 个最常见报错的排查方法和解决方案（2026 年含工信部安全通报应对）

我自己部署 OpenClaw 的过程中踩了不下 30 个坑。后来帮朋友们部署，又踩了一遍同样的坑。更要命的是，2026 年 3 月工信部的安全通报之后，很多人仓促修改配置，反而引入了新的问题。

这篇文章把我和周围开发者实际遇到的 20 个最高频错误整理出来，按出现频率排序。遇到问题先来这里 Ctrl+F 搜一下，80% 的情况不用再去翻 GitHub Issues。

一、安装与启动类（出现率最高）

错误 1：Docker 容器启动后秒退

现象：docker compose up -d 执行成功，但 docker ps 看不到容器或显示 Exited(1)。

排查步骤：

docker logs openclaw-agent 2>&1 | tail -30

常见原因（按概率排序）：

1. 环境变量缺失（占 60%）：.env 文件不完整。必填项：至少一个模型的 API Key（OPENAI_API_KEY 或 ANTHROPIC_API_KEY），加 GITHUB_TOKEN。漏掉任何一个都会导致启动失败。我第一次部署就是因为 .env 文件里多了一个空格导致 Key 无效。
2. 端口冲突（占 20%）：默认的 3000 和 8080 端口可能被 Node.js 项目或 Nginx 占用。用 lsof -i :3000 检查，然后在 docker-compose.yml 里改端口映射。
3. 内存不足（占 15%）：OpenClaw 至少需要 2GB 可用 RAM。用 free -h 检查。如果是 1C1G 的丐版服务器，你得先加 swap：sudo fallocate -l 4G /swapfile && sudo mkswap /swapfile && sudo swapon /swapfile

错误 2：国内拉取 Docker 镜像超时

原因：Docker Hub 在国内网络环境下经常超时。

解决：配置国内镜像加速器。编辑 /etc/docker/daemon.json：

{
  "registry-mirrors": [
    "https://mirror.ccs.tencentyun.com",
    "https://hub-mirror.c.163.com"
  ]
}

然后 sudo systemctl restart docker。如果你用阿里云，它有专属的加速地址，在容器镜像服务控制台可以找到。

更好的方案：2026 年阿里云计算巢和腾讯云 Lighthouse 都有预置的 OpenClaw 镜像，零配置 10 分钟部署，完全跳过 Docker 镜像拉取的问题。

错误 3：permission denied 权限问题

解决方法有两种（选一个就行）：

# 方法 A：把当前用户加入 docker 组
sudo usermod -aG docker $USER && newgrp docker

# 方法 B：直接用 sudo
sudo docker compose up -d

二、API 连接类

错误 4：Connection refused — 连不上 AI 模型

排查清单：

1. API Key 是否有效？curl -H "Authorization: Bearer $OPENAI_API_KEY" https://api.openai.com/v1/models | head
2. 服务器能否访问外网？curl -I https://api.openai.com
3. 如果在国内服务器，需要配置 HTTP 代理：在 .env 中加 HTTP_PROXY=http://your-proxy:port、HTTPS_PROXY=http://your-proxy:port

我有一次排查了 2 小时发现是 API Key 过期了（OpenAI 会定期过期旧 Key）。现在我养成了一个习惯：每次 API 报错，第一件事就是用 curl 直接测 Key——排除最简单的原因。

错误 5：429 Too Many Requests — API 限频

原因：并发请求超过 API 速率限制。OpenClaw 默认可能并发多个 Agent 任务，每个都在疯狂调 API。

解决：

• 降低并发：在配置中设置 max_concurrent_tasks: 1
• OpenAI 用户：升级 API Tier（需要历史充值 > $50）
• 切换模型：Gemini 3 Pro 的 API 限频比 OpenAI 宽松得多
• 加 retry 配置：api_retry_count: 3、api_retry_delay_ms: 5000

错误 6：context_length_exceeded — 上下文溢出

这是 Agent 场景的常见问题。你的项目文件太多，Agent 贪心地全读了一遍，上下文就爆了。

解决（按优先级）：

1. 添加 .clawignore 文件排除大目录（node_modules、.next、dist、coverage、.git、*.lock）
2. 限制上下文：max_context_files: 8
3. 换长上下文模型：Gemini 3 Pro（100 万 token）几乎不会遇到此问题

三、Task 执行类

错误 7：Task 卡死不动

排查：docker logs -f openclaw-agent 看实时日志

常见原因：

• Agent 在等你确认：检查是否需要开启 auto_approve: true
• API 超时：设置 timeout: 120（秒）
• 死循环：Agent 反复修改同一个文件但始终编译不过。设置 max_iterations: 25 强行终止

我踩过的一个坑：Agent 陷入了"修 A 文件 → 导致 B 文件报错 → 修 B → 导致 A 又报错"的死循环。后来发现是 Task 描述太模糊（"修掉所有 Bug"），改成精确描述（"修复 src/lib/xxx.ts 中的 XX 函数"）后问题消失了。

错误 8：Agent 修改了不该改的文件

预防措施：

• 在 Task 描述中明确限制："只修改 src/lib/payment/ 目录下的文件"
• 开启 Git diff 审查：require_diff_review: true
• 使用 sandbox 模式：修改不直接写入磁盘，先暂存供你审查

错误 9：Git commit 失败 — Author identity unknown

容器里没配 Git 用户信息。在 docker-compose.yml 的 environment 中加：

GIT_AUTHOR_NAME: "OpenClaw Agent"
GIT_AUTHOR_EMAIL: "[email protected]"
GIT_COMMITTER_NAME: "OpenClaw Agent"
GIT_COMMITTER_EMAIL: "[email protected]"

四、安全类（2026 年 3 月工信部通报后必看）

错误 10：端口暴露到公网（严重！）

2026 年 3 月工信部的安全通报指出：大量 OpenClaw 实例因默认配置将端口暴露到公网，攻击者可以直接调用你的 Agent 执行任意命令——包括读取你的 API Key、操作你的代码仓库。

立即修复：在 docker-compose.yml 中把端口绑定到 127.0.0.1：

ports:
  - "127.0.0.1:3000:3000"
  - "127.0.0.1:8080:8080"

然后通过 Nginx 反向代理 + 密码认证来暴露服务。详细配置请看 → OpenClaw 安全加固指南

错误 11：API Key 泄露到 Git 仓库

确保 .env 在 .gitignore 中。如果已经泄露（出现在 Git 历史中）：

1. 立即去 OpenAI/Anthropic 后台 吊销旧 Key 并重新生成
2. 用 git filter-branch 或 BFG Repo-Cleaner 从历史中删除

错误 12：技能插件安全风险

OpenClaw 的 6000+ 技能插件来源广泛，部分社区插件可能包含恶意代码。建议：

• 只安装官方或可信来源的技能
• 在隔离环境中测试新技能
• 避免将 API Key 等敏感数据直接写入 Prompt 中传给插件
• 定期审查已安装插件的权限和更新日志

五、性能与资源类

错误 13：内存 OOM — 服务器被杀

OpenClaw + Docker 运行时约占 1.5-2GB RAM。如果同时跑多个 Agent 任务，内存消耗会翻倍。

解决：限制 Docker 内存上限，在 docker-compose.yml 中加：

deploy:
  resources:
    limits:
      memory: 2G

并且增加 swap 作为缓冲。

错误 14：磁盘空间不足

Docker 镜像 + 日志 + Agent 工作目录的缓存文件会迅速占满磁盘。用 df -h 和 docker system df 排查。清理命令：docker system prune -a --volumes（会删除所有未使用的镜像和卷，谨慎！）

错误 15：日志文件太大

在 docker-compose.yml 中限制：

logging:
  driver: "json-file"
  options:
    max-size: "10m"
    max-file: "3"

六、GitHub 集成类

错误 16：GitHub Token 权限不足

确认 Token 具有 repo、workflow 权限。推荐使用 Fine-grained Personal Access Token（只授权给特定仓库），比 Classic Token 安全。

错误 17：PR 创建失败

检查 Token 是否有 pull_request:write 权限。如果是 fork 的仓库，需要从 fork 发 PR 到上游。

七、Telegram 集成类

错误 18：Bot 不响应消息

三个排查点：1) TELEGRAM_BOT_TOKEN 是否正确 2) 是否已 /start 过 Bot 3) 国内服务器能否访问 api.telegram.org（需代理）

八、升级与维护类

错误 19：升级后配置不兼容

升级前必做：备份 .openclaw/ 目录和 .env 文件。升级后阅读 CHANGELOG 检查 breaking changes。2026 年 3 月 v2.4 版本就改了配置文件的 YAML 结构，很多用户升级后 Agent 启动报语法错误。

错误 20：Chrome 实时会话功能不工作

2026 年 3 月新增的 Chrome 浏览器实时会话链接功能需要额外安装 Chrome 扩展。确保：1) 安装了官方浏览器扩展 2) 在扩展设置中输入了 OpenClaw 的 WebSocket 地址 3) 服务器 WebSocket 端口对外可达（通过 Nginx 代理）。