OpenClaw 实战避坑指南：10 个长期运维才会踩到的坑

用了这么久 OpenClaw，踩过的坑比用过的功能还多。这篇文章不写「什么是 OpenClaw」那种入门介绍，只讲真正用得上的技巧——那些文档里不会重点写、但实际部署后会立刻遇到的问题。

本文基于一台长期运行的 OpenClaw 实例（版本 2026.8.1，Linux 服务器，接微信渠道）的真实运维经验整理。

一、先搞懂它的三层结构，很多坑就不会踩

OpenClaw 的架构可以简化成三层：

• Gateway（网关）：核心进程，管会话、模型、工具、渠道。默认监听 18789 端口。
• Channel（渠道）：微信、企微、Telegram、Discord 等接入层，每个渠道独立维护自己的连接。
• Agent（智能体）：实际干活的「人设」，可以多个并行。

理解这三层之后，很多问题就好判断了：「消息发不出去」往往是渠道层的事，「回复很慢」可能是模型层，「工具调用失败」才是 Agent 层。

二、排查问题的第一件事：跑 status 和 doctor

openclaw status      # 全局状态：服务、渠道、agent、任务
openclaw doctor      # 健康检查 + 自动修复建议
openclaw health      # 只问网关健康

很多人出问题就开始翻日志，其实 OpenClaw status 一眼就能看出是哪一层挂了。doctor 更狠——它会把配置里过时或冲突的项直接指出来，并且支持 --fix 自动修。

三、渠道故障最常见的一种：主动推送失败

这是最容易让人误判的问题。症状很迷惑：

• 你发消息，AI 能正常回复 ✅
• 但定时任务、主动通知发不出去 ❌

日志里通常是：

sendMessage ret=-2 errmsg=prepare failed

为什么会这样？ 因为「被动回复」和「主动推送」走的是两条路径。被动回复是用户在会话里触发的，通道连接是热的；主动推送需要通道自己发起一次全新发送，如果渠道的登录会话失效，这一路就会失败，而被动回复照样正常。

排查要点：别把目光放在配置和代码上，先看渠道会话是否还活着。openclaw channels status 显示 running 不代表主动推送能用。常见的恢复方式是重启渠道或重启网关。

四、网关重启：看着简单，其实有讲究

重启网关是最高频的操作，但这里有两个坑：

1. 系统级服务不能用用户级命令

如果网关装成了 systemd 系统服务，openclaw gateway restart 会直接告诉你不行，必须：

sudo systemctl restart openclaw-gateway.service

2. 重启会掐断你正在进行的会话

因为网关就是你在用的东西——重启它会把你当前的对话进程一起断掉。这是正常的，恢复后会自动接上，但别在长任务跑到一半时重启。

3. 重启后先验证，再干别的

systemctl is-active openclaw-gateway.service
curl -s -o /dev/null -w "%{http_code}" http://127.0.0.1:18789/

返回 200 才算真的起来了。

五、远程访问：ws 和 wss 的区别不是「加密」这么简单

想让手机 App 或远程客户端连上 Gateway，很多人第一反应是开个端口用 ws://。但实际会撞墙：

• 公网 ws:// 会被拒绝或降级：明文传输，官方客户端会 fail-closed，只给你「受限权限」。
• 想要完整权限，必须 wss://（TLS 加密）或走 Tailscale。

用 nginx 反代的三个必要条件

location / {
    proxy_pass http://127.0.0.1:18789;
    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_set_header X-Forwarded-For $remote_addr;
    proxy_read_timeout 3600s;
}

关键坑：配完 nginx 会返回 403，提示 proxy_attribution_required。

这是 OpenClaw 的安全机制——它拒绝来源不明的代理转发头。必须配置：

openclaw config set gateway.trustedProxies '["127.0.0.1"]'

而且这个配置的 reloadKind 是 restart，改完必须重启网关才生效。另外注意 X-Forwarded-For 要用 $remote_addr（重建），不要用 $proxy_add_x_forwarded_for（追加），否则会让攻击者伪造 IP。

六、定时任务：写对了才叫自动化

OpenClaw 的 automations（别名 cron）是很好用的功能，但有几个必须知道的点：

1. 任务必须能「失败可见」

如果你写了个「只在数据变化时推送」的任务，那么当渠道推送坏了、数据又恰好没变化时，任务会静默失败——你什么都不会收到，还以为它在正常工作。

2. 命令行任务的输出必须干净

带 --command 的任务，输出内容会作为消息发出去。所以脚本里不要打印调试信息，否则你会收到一堆垃圾消息。想「没变化就不发」，就输出固定字符串让任务自己判断。

3. 定时任务和主会话是隔离的

任务默认在 isolated 会话里跑，看不到你主会话的上下文。要让它带上下文，得显式配置。

七、记忆系统：它不记得你，除非你让它记

这是 OpenClaw 最容易被误解的功能。它每次会话都是全新启动，靠的是文件来延续：

• memory/YYYY-MM-DD.md：每日日志，原始记录
• MEMORY.md：长期事实和决策（只在主会话加载）
• USER.md：你的偏好和画像

实用技巧：

• 重要的事明确说「记下来」，它才会写进文件
• 跨会话要延续的信息，最好写在 MEMORY.md 或 USER.md，别指望它自己想起来
• 如果它「忘记」了，先看对应日期的记忆文件在不在——很多时候是没写，不是没读

记忆写入的坑

自动整理记忆的任务（比如定时总结）容易失败，常见原因是编辑时文本不匹配：破折号是全角还是半角、箭头符号、多余空格，都会让 edit 失败一次。经验是：先读再改，一次只改一小段，确保匹配当前的确切字节。

八、配置改动的正确姿势

OpenClaw 的配置都在 openclaw.json 里。改配置有几个规矩：

• 改之前先备份：cp openclaw.json openclaw.json.bak.$(date +%s)
• 用 CLI 改，别手写 JSON：openclaw config set <key> <value> 会校验格式
• 看检查结果：openclaw config validate
• 注意 reloadKind：有的配置改完自动生效，有的必须重启网关

另外一个真实教训：改配置前先 openclaw config get 看一眼现值。很多「改了没生效」其实是改错了路径，或者被更上层的配置覆盖了。

九、安全：默认值是「保守」的，但你别乱开

OpenClaw 有不少安全默认值，比如：

• 公网明文 ws:// 自动降权
• 代理转发头必须显式信任
• 执行命令需要审批

不要为了方便把这些关掉，尤其是把 bind 改成 lan 又把安全项关掉——管理端口暴露在公网上，被扫到只是时间问题。

推荐做法：

• 能走 Tailscale 就别开公网
• 必须开公网，就用 wss:// + 强密码
• 用 nginx 做一层，只暴露必要的路径

十、升级：升级前必做三件事

1. 看 CHANGELOG：直接读包目录里的 CHANGELOG.md，重点看 Breaking Changes（破坏性变更）那一段。
2. 备份：配置 + 记忆目录 + 数据库。
3. 升完立刻 doctor --fix：它会自动迁移过时的配置项（比如模型名变更、插件路径变更）。

我自己踩过的：某次升级后模型引用格式变了（从 codex/* 变成 openai/*），不跑 doctor --fix 就一直在报模型不存在。

写在最后

OpenClaw 这类自托管 AI 助理，真正难的不是「装起来」，而是长期稳定地跑下去。上面这些经验，核心其实就三条：

• 出了问题先分层定位（Gateway / Channel / Agent），别上来就翻日志
• 任何配置改动都先备份、先看现值、改完验证
• 自动化任务要保证「失败可见」，否则它会在你最需要的时候悄悄死掉

希望这些经验能帮你少走点弯路。

本文基于 OpenClaw 2026.8.1 的实际部署与运维经验整理，具体行为以官方文档和实际版本为准。