夜雨聆风装openclaw那天，我信心满满。
文档写得清清楚楚，照着做就行。结果配到第3天，我对着屏幕产生了深深的怀疑：这破东西是不是有bug？为什么照着文档做就是不对？
5天后我终于配好了，头发掉了十几根。这篇文章写给正在配或者准备配openclaw的人，5个我踩过的坑，每个都有血有肉。
第一个坑让我差点直接放弃：Gateway启动失败，报错信息我看懂了但不知道怎么办。
我照着文档跑openclaw gateway start，它给我甩了一句Error: Port 3000 is already in use。端口被占，我第一反应是重装。重装了两次，问题依旧。后来拿netstat -ano查了半天，才发现是Docker里跑了另一个服务，占着3000端口。解决方法很简单，要么停掉那个服务，要么改openclaw的端口配置，在~/.openclaw/config.json里加一行gateway: {port: 3001}。文档里其实写了，但那个段落藏在中间，我压根没看到。这个坑让我浪费了三个小时。
第二个坑是Bot Token和User Token，我混用了两周才明白两回事。
openclaw有两个Token，Bot的和User的。我一开始拿到User Token，配进config.json，发消息就是石沉大海。后来才搞明白，Bot Token用来接收和发送消息，User Token用来操作用户数据，是两个完全不同的权限体系。配错了，要么发不出去，要么权限不够。更坑的是，两个Token格式几乎一样，肉眼根本看不出区别，文档也没有明确说明该用哪个。我最后是把两个都配上，调试的时候一个个试，才确定哪个场景用哪个。这个坑让我在群里发消息发了两周才找到问题根源。
第三个坑是cron表达式，差一个字段整个定时任务就不动。
openclaw的cron用的是标准5段式，字段顺序是分 时 日 月 周。我第一次配每日9点跑任务，写的是09:00 * * *，以为这意思是每天9点。结果定时任务一动不动，cron log里什么都没有。我以为是我的表达式格式不对，换了三四种写法都不行。最后翻了半天才找到官方文档，原来openclaw的cron字段顺序是分在前面，不是时在前面。我改成了0 9 * * *，任务立刻跑起来了。文档里确实写了这个顺序，但那段在很不起眼的位置，第一次配的人几乎都会踩。
第四个坑是Session Key，我到现在都没完全搞清楚所有参数含义。
openclaw的消息路由靠Session Key，格式大概是agent:main:main或者agent:writer:main。我第一次想给写作官发任务，直接用了agent:writer:main，结果消息消失得无影无踪。后来我用openclaw session list查了一下活跃session，才发现写作官的key是agent:writer:feishu:direct:ou_xxxxx，后面还跟了一串ID。更复杂的是，这个格式在私聊和群聊里不一样，在不同插件里也可能不一样。文档里只有几个示例，没有完整的格式说明。我在好几个场景里试错过，每次都要回头查session list才能找到正确的key。这个坑到现在都没完全解决，我只是学会了怎么快速查。
第五个坑是exec工具的权限，脚本跑一半被kill，没有任何报错。
我有一段时间在用openclaw做自动化推送草稿箱，脚本前面都跑通了，到最后一步调用微信API的时候，进程突然被kill。没有任何错误信息，没有任何log，就是突然没了。我以为是脚本本身的问题，试了十几种改法，结果都一样。后来翻了很久的文档，才发现openclaw的exec默认是安全模式，会拦截很多系统调用。需要手动在config.json里加上exec: {security: full}才能跑完整流程。打开之后，脚本立刻跑通了。这个配置项文档里没写，是在一个很偏的页面角落里找到的。
踩完这5个坑，我现在的看法是这样的：
openclaw是个好工具，能力边界很大，但文档和配置的复杂度也很大。文档有些地方写得很清楚，有些地方藏得很深，第一次配的时候真的很容易踩坑。这不是工具的问题，是我预期管理的问题——配之前应该先在脑子里把整个架构跑一遍，而不是拿到什么就直接往上配。
这篇文章就当是我的血泪教训吧，希望你配的时候比我顺利一点。
好，就说这么多。
