OpenClaw 跑不起来？20 个最常见报错的排查与解决方案（2026 年 7 月更新）

一句话摘要：OpenClaw 的报错八成集中在五类——Node 版本过低导致"没报错但不工作"、模型 API 连不上或被限频（429）、Agent 任务卡死、资源不足触发 OOM、以及服务端口暴露带来的安全风险。官方推荐用 openclaw onboard 引导式安装（建议 Node 24，最低 Node 22 LTS 22.19+），Agent 行为通过 SOUL.md 配置。下面 20 条按出现频率排序，每条都附可直接照做的命令。遇到问题先 Ctrl+F 搜你的报错。

最后更新：2026 年 7 月

OpenClaw 是开源（MIT）的自托管个人 AI 助手框架，跑在你自己的设备上，通过 Telegram、Slack、Discord、WhatsApp 等消息应用作为交互界面。它和 ChatGPT 最大的不同在于：ChatGPT 只告诉你"该怎么做"，OpenClaw 会真正去做——执行 shell 命令、读写文件、浏览网页、控制浏览器、发消息。能力越大，能出错的地方也越多。

这篇文章把部署和使用 OpenClaw 时最高频的 20 个错误整理出来，按出现频率排序。每条都尽量给出能直接复制执行的命令；涉及具体配置字段时，以 openclaw 官方文档为准，不照抄网上未经核实的键名。

一、安装与环境类（出现率最高）

错误 1：装好后"没报错但不工作"——Node 版本过低

现象：openclaw onboard 跑完了，Agent 却收不到消息、命令无响应，日志里也没有明显报错。

原因：这是新手最容易忽略的坑。OpenClaw 官方推荐 Node 24，最低要求 Node 22 LTS（22.19+）。低于最低版本时，很多功能会静默失败——不抛异常，但行为异常。

解决：

node -v            # 先看当前版本
# 用 nvm 升级到 Node 24
nvm install 24 && nvm use 24

升级后重新运行 openclaw onboard。

错误 2：openclaw onboard 没跑完，配置缺项

现象：引导安装中途 Ctrl+C 退出，或某一步被跳过，导致 Agent 起不来或消息渠道收不到消息。

说明：openclaw onboard 是官方推荐的引导式安装，会在终端里依次配置 gateway、workspace、channels（消息渠道）、skills（技能）。任何一步没配完，都可能让整套流程半死不活。

解决：重新完整跑一遍 openclaw onboard，按提示逐步补齐每一项。正常情况下大约 10 分钟能跑起来。

错误 3：Agent 一调用就失败——没接模型 API Key

关键概念：OpenClaw 是 Agent 框架，本身不自带大模型，必须接你自己的 LLM（API Key 或订阅）。没有配置有效的模型凭证，Agent 会在第一次调用时直接失败。

排查：至少配置一个可用模型（Claude / GPT / Gemini 均可），并用 curl 先确认 Key 本身有效——排除最简单的原因：

curl -H "Authorization: Bearer $OPENAI_API_KEY" https://api.openai.com/v1/models | head

注意 .env 或凭证文件里别多敲空格——一个多余的空格就能让 Key 失效。

错误 4：permission denied 权限问题

如果你用容器方式部署，容器操作权限不足很常见。两种解法选一个：

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

# 方法 B：临时用 sudo
sudo docker compose up -d

错误 5：国内拉取依赖/镜像超时

原因：npm 源和 Docker Hub 在国内网络下经常超时。

解决：npm 侧换国内镜像源；如果走容器，配置 Docker 镜像加速器，编辑 /etc/docker/daemon.json：

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

然后 sudo systemctl restart docker。阿里云用户可在容器镜像服务控制台找到专属加速地址。

二、容器化部署类（可选路径）

下面几条只适用于选择用 Docker 容器方式部署的情况。官方推荐路径仍是 openclaw onboard；具体镜像名、端口映射取决于你自己的 compose 配置，本节命令是通用的容器排查手法。

错误 6：容器启动后立刻退出

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

第一步永远是看日志：

docker logs <容器名> 2>&1 | tail -30

最常见的落地原因是环境变量缺失（模型 API Key 没配好）、端口冲突、或内存不足——分别对应下面几条。

错误 7：端口冲突

如果宿主机上已有 Node、Nginx 等占用了容器要映射的端口，容器会起不来。先查占用，再改 compose 里的端口映射：

lsof -i :3000

错误 8：内存不足，容器被杀

OpenClaw 官方给出的最低配置约为 2 核 CPU / 4GB 内存 / 100GB 磁盘。先用 free -h 看可用内存。如果是 1 核 1G 的低配机，先加 swap 当缓冲：

sudo fallocate -l 4G /swapfile && sudo mkswap /swapfile && sudo swapon /swapfile

（非容器、直接运行的场景下同样会因内存不足被系统杀掉，见错误 18。）

三、模型 API 连接类

错误 9：Connection refused — 连不上模型

排查清单：

1. Key 是否有效？用上面错误 3 里的 curl 直接测。
2. 服务器能否访问外网？curl -I https://api.openai.com
3. 国内服务器访问境外模型 API 时，往往需要配置 HTTP 代理（HTTP_PROXY / HTTPS_PROXY 环境变量）。

经验：每次 API 报错，第一件事就是 curl 直接测 Key，先排除"Key 过期/失效"这类最简单的原因，再去查复杂配置。

错误 10：429 Too Many Requests — 被限频

原因：并发请求超过了模型服务商的速率限制。Agent 场景下多个任务同时调 API，很容易撞上。

解决方向（具体配置字段名以 openclaw 官方文档为准，别照抄网上未经核实的键名）：

• 降低 Agent 并发数，让请求排队而不是一拥而上。
• 给 API 调用加重试与退避（指数退避重试）。
• OpenAI 用户可提升 API Tier 档位（通常与历史充值额度挂钩）。
• 换一个限频更宽松的模型作为兜底。

错误 11：context_length_exceeded — 上下文溢出

这是 Agent 场景的高频问题：项目文件太多，Agent 一股脑全读进上下文就爆了。

解决（按优先级）：

1. 让 Agent 尊重忽略规则，排除大目录（node_modules、.next、dist、coverage、.git、各种 lock 文件）；具体忽略文件的名称与位置以官方文档为准。
2. 限制单次读入的文件数量。
3. 换用长上下文模型（如 Gemini 3.1 Pro）来缓解——把整个大项目塞进单次对话时，更大的上下文窗口能明显降低溢出概率。

四、Agent 任务执行类

错误 12：Task 卡死不动

排查：先看实时日志，判断 Agent 究竟卡在哪。

docker logs -f <容器名>    # 容器方式；直接运行则看对应日志文件

常见原因：Agent 在等你人工确认某个动作；API 请求超时；或陷入死循环（反复改同一个文件却始终编译不过）。

一个典型的死循环是"修 A 文件 → 导致 B 文件报错 → 修 B → A 又报错"。多数情况根因是 Task 描述太模糊（比如"修掉所有 Bug"）。把任务改成精确描述（"修复 src/lib/xxx.ts 里的 XX 函数"）后，这类循环往往就消失了。同时可在配置里设置最大迭代次数做兜底强制终止。

错误 13：Agent 改了不该改的文件

预防措施：

• 在 Task 描述里明确限定范围，例如"只修改 src/lib/payment/ 目录下的文件"。
• 先审后落：让改动先以 diff 形式呈现、由你确认后再写盘。
• 启用沙箱执行，把 Agent 的动作限制在隔离环境里（见下方"安全类"的 NemoClaw）。

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

运行环境里没配 Git 用户信息。设置提交身份即可（容器部署则写进对应的环境变量）：

git config --global user.name  "OpenClaw Agent"
git config --global user.email "[email protected]"

五、安全类（自托管 Agent 的重中之重）

错误 15：服务端口暴露到公网（最严重）

OpenClaw 能真正执行任意 shell 命令、读写文件、操作浏览器。一旦服务端口直接暴露到公网且没有认证，等于把一台能执行任意命令的机器开放给所有人——攻击者可以读走你的 API Key、操作你的代码仓库。这是自托管 Agent 被反复提醒的头号风险，务必自查。

立即修复：把监听端口绑到本地回环 127.0.0.1，再通过带认证的反向代理对外暴露。以 Docker 端口映射为例：

ports:
  - "127.0.0.1:3000:3000"

然后在前面套一层 Nginx 反向代理 + 密码认证。详细配置见 → OpenClaw 安全加固指南。

可用的沙箱方案：NVIDIA 于 2026 年 3 月发布了 NemoClaw 安全插件（基于 OpenShell 沙箱），能把 Agent 的命令执行限制在隔离环境中。生产环境值得启用它来收窄"Agent 乱执行"的爆炸半径。

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

确保 .env（及一切含密钥的文件）在 .gitignore 里。如果已经进了 Git 历史：

1. 立即到 OpenAI / Anthropic / Google 后台吊销旧 Key 并重新生成——这一步永远优先于清历史。
2. 再用 BFG Repo-Cleaner 或 git filter-repo 把敏感内容从历史里彻底删除。

错误 17：第三方技能/插件的安全风险

OpenClaw 生态里有大量社区技能和 SOUL.md 模板（社区已积累了上百个可复用的 SOUL.md 模板）。要注意：第三方技能拿到的是与 Agent 相同的执行权限，来源不明的插件存在风险。建议：

• 只安装官方或可信来源的技能。
• 新技能先在隔离环境里试跑。
• 不要把 API Key 等敏感数据直接写进传给插件的 Prompt。
• 定期审查已装插件的权限和更新记录。

六、性能与资源类

错误 18：内存 OOM — 进程被系统杀掉

同时跑多个 Agent 任务时内存消耗会明显上升，逼近 4GB 最低线时容易被 OOM Killer 干掉。容器部署可给容器设内存上限并配合 swap 缓冲：

deploy:
  resources:
    limits:
      memory: 2G

错误 19：磁盘占满 / 日志膨胀

镜像、日志、Agent 工作目录缓存会迅速吃满磁盘。先排查再清理：

df -h
docker system df
docker system prune -a --volumes   # 会删除所有未使用的镜像和卷，谨慎执行

容器方式可给日志设上限，避免单个日志文件无限增长：

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

七、渠道与集成类

错误 20：消息渠道 Bot 不响应（Telegram 等）

OpenClaw 通过消息应用作为交互界面，Bot 不回消息通常卡在三点：

1. 渠道的 Token / 凭证是否填对（比如 Telegram 的 Bot Token）。
2. 是否已经在对应 App 里主动和 Bot 建立过会话（Telegram 需要先 /start）。
3. 国内服务器能否访问该渠道的服务器（如 api.telegram.org，通常需要代理）。

同理，GitHub 集成失败多是 Token 权限不足——推荐用 Fine-grained Personal Access Token 只授权给特定仓库，比 Classic Token 更安全。

常见问题（FAQ）

Q：OpenClaw 到底是什么？和 ChatGPT 有什么区别？
A：OpenClaw 是开源（MIT）的自托管个人 AI 助手框架，跑在你自己的设备上，通过 Telegram / Slack / Discord / WhatsApp 等消息应用交互。和 ChatGPT 只"告诉你怎么做"不同，OpenClaw 会真正执行任务：跑 shell 命令、读写文件、浏览网页、控制浏览器、发消息。它不自带模型，需要你接自己的 LLM。

Q：安装用 Docker 还是 openclaw onboard？
A：官方推荐在终端运行 openclaw onboard 引导式安装，会依次配置 gateway、workspace、消息渠道和技能，大约 10 分钟能跑起来。Docker 是可选的容器化路径，适合已有容器编排习惯的人。新手建议先走 onboard。

Q：为什么装好却"没报错但不工作"？
A：最常见是 Node 版本过低。官方推荐 Node 24，最低 Node 22 LTS（22.19+）。低于最低版本时很多功能会静默失败——不抛错但行为异常。先 node -v 检查，用 nvm 升级到 24 再重试。

Q：出现 429 限频怎么办？
A：降低 Agent 并发、给 API 调用加重试与退避、必要时提升 API 套餐档位，或换一个限频更宽松的模型兜底。具体的并发/重试字段名以 openclaw 官方配置文档为准，不要照抄网上未经核实的键名。

Q：OpenClaw 有哪些必须重视的安全风险？
A：最关键的是服务端口不要直接暴露到公网——OpenClaw 能执行任意命令，裸奔的端口等于把机器交给陌生人。把端口绑到 127.0.0.1，前面用带认证的反向代理；生产环境可启用 NVIDIA 的 NemoClaw 沙箱插件。API Key 放进 .gitignore，第三方技能只用可信来源。

Q：OpenClaw 最低需要什么配置？
A：官方给出的最低配置约为 2 核 CPU / 4GB 内存 / 100GB 磁盘。1 核 1G 的低配机需要先加 swap 才能勉强跑，且同时执行多个任务时容易 OOM。

Q：OpenClaw 需要付费吗？钱花在哪？
A：OpenClaw 框架本身开源免费。真正的花费在你接入的模型订阅或 API 用量上——这也是唯一必须付费的部分。日常使用可选 Claude、ChatGPT 或 Gemini 的订阅或 API。