OpenClaw 实战避坑：从 gateway 配置到 skill 加载的问题记录与 tips 汇总

1. OpenClaw 的 gateway、skill 与 agent 到底卡在哪OpenClaw 是一个把大模型、工具调用、浏览器自动化和多 agent 协作揉在一起的本地智能体框架你能用它做搜索、写代码、整理文件、跑定时任务甚至接飞书、TG、Discord 当聊天入口。它适合已经上手、但被 gateway 连接、skill 加载、agent 调用反复折磨的开发者。我踩过的坑基本集中在三块一是 gateway 起不来或者起来后不回消息二是 skill 装了但 AI 不调用或者调用报错三是 agent 之间工作区、session 互相污染。这篇不聊安装直接给你一份可复制的 config.toml 骨架、逐步验证动作以及一份能反复用的排错清单。先说结论OpenClaw 的绝大多数“玄学问题”本质是配置字段和当前版本不匹配。它更新太快很多字段名、层级、默认值在几个小版本之间就变了你让大模型凭记忆改配置它很容易给你一个上个版本才存在的字段gateway 直接启动失败。所以第一步不是修功能是防止它把自己改死机。2. 先给 OpenClaw 配一个“急救机器人”配置改崩是高频事故。我的做法是装一个极小的机器人 NanoBot专门用来在 OpenClaw 挂掉时帮你改配置、修 gateway。它比 OpenClaw 小很多部署轻逻辑简单不容易被复杂配置带崩。你只需要对 OpenClaw 说一句帮我部署这个项目: https://github.com/HKUDS/nanobot 大模型相关配置参考当前 openclaw.json后续任何配置改动都优先让 NanoBot 来做。改崩了让它修比你自己手改快得多。这一步的价值在于你有了一个独立于 OpenClaw 的“配置操作台”不会出现主程序起不来、你连改配置的入口都没有的尴尬。同时记一个 todoOpenClaw 更新快配置字段容易让大模型产生幻觉哪怕联网搜索也可能搜到过期字段。建议你写一个 skill 专门做“配置字段校验”或者去社区搜现成的。这个后面排错清单里会再提。3. 可复制的 config.toml 骨架与关键字段下面这份骨架是我实测能跑通的最小结构字段名以你当前版本为准重点是层级关系别写错。写错层级是 gateway 启动失败最常见的原因。# ~/.openclaw/config.toml [gateway] host 127.0.0.1 port 18789 log_level info [model] provider openai-compatible base_url https://taotoken.net/api api_key sk-你的key model claude-3-5-sonnet [session] reset_mode idle idle_minutes 1440 [tools] profile full [tools.exec] ask off [agents.default] workspace workspace-default几个容易踩的点。第一base_url和api_key必须成对出现只填一个 gateway 会在初始化模型客户端时报错但报错信息往往指向别处很难查。第二[tools.exec]的ask字段本意是让 AI 问你“能不能执行”但实际行为是 AI 会优先让你自己去执行而不是问你。想让它真正动手把ask设为off同时确认profile full。第三session的重置模式默认机制会导致“第二天失忆”昨晚的对话早上全没了把idle_minutes调大能缓解。如果你要多 agent 独立工作区每个 agent 一个 workspace 文件夹默认命名是workspace-{agent名字}这样每个 agent 的 soul、memory、tool 都能不同互不干扰。4. 逐步验证从 gateway 到 skill 到 agent配置写完别急着上业务按下面顺序验证每步都有明确的成功信号。第一步验证 gateway 能起来openclaw gateway start openclaw gateway status成功信号是 status 返回 running且日志里没有字段解析错误。如果起不来先看日志第一行报的是哪个字段八成是字段名或层级不对。第二步验证模型能通。用模型对话入口发一句最简单的openclaw chat 你好回复ok返回 ok 说明模型链路通了。这一步不通后面 skill 和 agent 全是白搭。模型选型上实测 Claude Opus 的价格大约是 MiniMax、GLM 的 40 倍左右用量大建议换性价比高的但需要多模态就还得用 Claude、Gemini 这类。第三步验证 skill 加载。装一个搜索类 skill 试帮我安装 multi-search-engine装完让它搜一个技术问题看它是否真的调用。如果 AI 不自动调用联网搜索把工具选择规则写进Tool.md明确优先级multi-search-engine 首选tavily-search 次选web_fetch 兜底web_search 弃用。规则写清楚AI 才不会明明有免费方案还让你配 API key。第四步验证 agent 调用。多 agent 用openclaw agents add 名字再配频道。发布任务时告诉 OpenClaw 开启 sub_session它会用当前工作区配置开一个临时子会话并行干活。5. 本篇常见报错排查清单gateway 启动失败九成是配置字段和版本不匹配。别让大模型凭记忆改用 NanoBot 改或者写个字段校验 skill。改完先openclaw gateway stop再 start。飞书机器人不回消息升级到 2026.3.2 后或改了session.dmScope后飞书里机器人有用表情回复、dashboard 也看得到回复但飞书里看不到后台报 openid cross 错误。解决方式是停 gateway手动删 session 缓存目录~/.openclaw/agents/agent-name/session再启动。还不行就把/feishu目录删了。原理是飞书插件缓存了用户 open_id配置或版本一变就对不上删缓存强制重新获取。这个等待官方修复急用可以换 TG 或 Discord流畅度高、bug 少。飞书 API 额度被心跳耗光飞书 API 每月 5 万次月初刷新。8 个 agent、每个 10 分钟心跳一次一个月就是 3 万多心跳额度基本见底。改插件src/probe.ts里的心跳时间把 10 分钟改成 24 小时能大幅减少无用调用。插件位置问 OpenClaw 就行。AI 变笨、不执行命令而是让你执行3.2 到 3.7 版本加强了安全需要改openclaw.json和exec-approvals.json把tools.exec.ask设为offdefaults.security设为full。注意这等于允许执行一切指令、永不审批有风险建议配合指令白名单具体看官方 exec 和 exec-approvals 文档。skill 太多导致选错超过 20 个工具AI 准确率明显下降。分层管理核心层常驻 5 到 12 个搜索、浏览器、文件、记忆工具层 10 到 20 个git、Notion、调试动态层按需装用 find-skills 让 AI 自己找。别追求装下所有 skill追求“需要时能立刻找到并装上”。skill 投毒目前存在大量投毒 skill安装前先用 skill-vetter 扫描优先在隔离环境装选全绿的 skill。OpenClaw 自带提示词防御已经不错但弱模型仍可能被攻击导致泄露 apikey 甚至电脑被控。记忆搜不准自带 memory-core 只有纯向量搜索存得多搜得乱。QMD 加混合检索BM25 加向量加 rerank搜得更准memory-lancedb-pro 是完整升级支持混合检索、rerank、时间衰减、多 scope 隔离、自动捕获回忆需要 Jina 免费 key。两个可以一起用QMD 是图书馆pro 是大脑。6. 把模型接入和排错沉淀成可复用流程上面所有验证动作里模型链路是最底层的一环它不通skill 和 agent 都无从谈起。我现在的做法是把模型接入统一走一个兼容 OpenAI 协议的入口配置里只改base_url和api_key两个字段换模型不动其他结构排错时也能快速排除“是不是模型侧的问题”。如果你也在被 gateway 连接、skill 加载、agent 调用反复卡住建议先把模型接入这层固定下来API Key 在控制台生成接入方式看接入文档验证模型是否通直接用模型对话发一句话最快。长期跑编码和 agent 任务的话Coding Plan 比按量更省心。把这几步跑顺再回头调 skill 和 agent你会发现大部分“玄学报错”其实都出在配置字段和缓存上而不是框架本身。