OpenClaw 使用避坑指南：从安装到实战的踩坑记录

砸了你的缸
12 阅读4分钟

前言

OpenClaw 是一个开源的 AI 助手框架，可以让 AI 接入你的终端、浏览器、消息平台（Telegram、Discord、WhatsApp 等），成为一个真正能"动手"的个人助手。

听起来很酷对吧？确实很酷。但安装和使用过程中，坑也不少。这篇文章记录了我在实际使用中踩过的坑，希望能帮后来人少走弯路。

坑 1：WSL2 环境下浏览器控制不了

问题描述

在 WSL2 里安装 OpenClaw 后，执行浏览器操作时一直超时：

Can't reach the OpenClaw browser control service (timed out after 15000ms)

原因分析

WSL2 和 Windows 是两个独立的网络命名空间。即使你把 browser.executablePath 指向 Windows 的 Chrome（/mnt/c/Program Files/Google/Chrome/Application/chrome.exe），Chrome 会在 Windows 侧启动，CDP（Chrome DevTools Protocol）端口绑定在 Windows 的 127.0.0.1，WSL 里的 OpenClaw 根本连不上。

解决方案

推荐：使用 Browser Relay 扩展

  1. 在 Windows 的 Chrome 中安装 OpenClaw Browser Relay 扩展
  2. 扩展默认连接 http://127.0.0.1:18792
  3. 在需要控制的标签页上点击扩展图标，badge 变为 ON
  4. OpenClaw 就能通过 Relay 控制已附加的标签页

注意：Browser Relay 不能主动打开新标签页，需要你先手动打开目标页面再附加。

坑 2：systemctl 在 WSL2 里不可用

问题描述

执行 openclaw gateway restart 时报错：

System has not been booted with systemd as init system

解决方案

两个选择：

  1. 启用 WSL2 的 systemd 支持：在 /etc/wsl.conf 中添加：
[boot]
systemd=true

然后 wsl --shutdown 重启 WSL。

  1. 手动管理进程：直接 Ctrl+C 停掉 OpenClaw，重新运行 openclaw 启动。

坑 3：配置文件修改后不生效

问题描述

修改了 ~/.openclaw/openclaw.json 中的配置（比如 browser.executablePath），但重新操作时发现没有变化。

原因

OpenClaw Gateway 在启动时读取配置，运行中修改配置文件不会热加载。

解决方案

修改配置后必须重启 Gateway：

openclaw gateway restart
# 或手动重启进程

推荐使用 CLI 命令修改配置，部分配置可即时生效：

openclaw config set browser.headless true

坑 4：Node.js 版本不兼容

问题描述

安装 OpenClaw 时报各种奇怪的语法错误或模块找不到。

解决方案

OpenClaw 需要 Node.js 18+，推荐 v22 LTS：

# 使用 nvm 管理版本
nvm install 22
nvm use 22
npm install -g openclaw

坑 5：API Key 配置容易搞混

问题描述

OpenClaw 支持多种 AI 模型提供商（OpenAI、Anthropic、自定义网关等），配置时容易搞混字段名。

最佳实践

# 使用交互式配置，不容易出错
openclaw setup

# 或者明确指定
openclaw config set ai.provider anthropic
openclaw config set ai.apiKey sk-xxx

小心不要把 API Key 提交到 Git 仓库！openclaw.json 默认在 ~/.openclaw/ 目录下，不在工作区内。

坑 6：消息平台连接断开后不自动重连

问题描述

连接 Telegram/Discord 后，网络波动导致断开，有时不会自动恢复。

解决方案

  • 检查 Gateway 是否还在运行：openclaw gateway status
  • 重启 Gateway 通常可以恢复连接
  • 对于 WhatsApp，可能需要重新扫码

坑 7：工作区权限和安全

注意事项

OpenClaw 的 AI 助手能访问你的文件系统、执行命令。虽然有安全策略，但还是要注意：

  1. 不要在 root 用户下运行 OpenClaw
  2. 工作区（workspace） 默认在 ~/.openclaw/workspace，AI 主要在这里操作
  3. 敏感文件 不要放在工作区里
  4. 外部操作（发邮件、发消息）AI 应该先征求你同意

总结

坑核心原因解决思路
浏览器控制失败WSL2 网络隔离用 Browser Relay 扩展
systemctl 不可用WSL 默认无 systemd启用 systemd 或手动管理
配置不生效需要重启 Gateway改完重启
Node.js 报错版本太低用 v22 LTS
API Key 混乱字段名易混用 openclaw setup
连接断开网络波动重启 Gateway
安全问题权限过大非 root 运行 + 注意工作区

OpenClaw 还在快速迭代中，很多问题在新版本中可能已经修复。建议关注 GitHub 和 Discord 社区 获取最新动态。

如果这篇文章帮到了你，欢迎点赞收藏，也欢迎在评论区分享你遇到的坑！

avatar
文章
阅读
粉丝