别再信「一键部署」了——我花一周调试 OpenClaw 的真实经历与踩坑干货

tommychian

1040人浏览 · 2026-03-28 12:28:08

tommychian · 2026-03-28 12:28:08 发布

本文记录了我从安装 OpenClaw 到让飞书 Agent 真正「能干活」的全过程。13 个真实踩坑案例、多模型协作架构设计、以及那些媒体不会告诉你的坑。

一、写在前面：小龙虾没有媒体说的那么简单

最近 AI Agent 赛道很火，OpenClaw（江湖人称「小龙虾」）作为一个开源的多 Agent 协作框架，被不少自媒体吹得天花乱坠——「一键部署」「零门槛上手」「10 分钟搭建你的 AI 助手」。

我信了。

然后我花了整整一周，几乎每天都在终端前敲命令、看日志、改配置、重启 Gateway、在飞书上反复测试。直到今天，我的飞书 Agent「钱多多」才算勉强达到「基本能干活」的状态。

这篇文章不是吐槽，而是一份真实的调试手记。如果你也想用 OpenClaw 搭建自己的 AI Agent，希望这些经验能帮你少走弯路。毕竟，别人踩过的坑，你不一定非要再踩一遍。

二、我的目标：在飞书上打造一个多功能 AI 助手

先说说我要做什么。我想在阿里云 ECS 上部署 OpenClaw，通过飞书作为前端，打造一个能做以下事情的 AI 助手「钱多多」：

日常对话：问答、翻译、写文章
金融数据查询：接入 TuShare，实时查 A 股行情，严禁编造数据
每日推送：早上 9 点自动推送财经要闻 + 真实行情数据
模拟炒股：Trader Agent 自主分析和模拟交易
多 Agent 协作：主 Agent 调度 4 个子 Agent（researcher、coder、writer、trader），各司其职
画图：通过 Gemini 模型生成图片

听起来很美好对吧？接下来就是现实给我上课的过程。

三、13 个真实踩坑案例（核心干货）

这是本文最硬核的部分。我把一周调试过程中遇到的 13 个坑全部记录了下来，每个坑都附带背景、现象、根因分析和解决方案。

🪤 坑 1：Agent 试图重启自己，结果把自己搞死了

备份系统翻车后，4 个子 Agent 没恢复成功。我让主 Agent 自己修改 openclaw.json 试图修复——结果它改完配置后，还尝试自己重启 Gateway。

后果：Gateway 进入异常状态，Agent 彻底无响应，直到第二天早上我手动在终端重启才恢复。

教训：Agent 运行在 Gateway 之上，让它重启 Gateway 就等于让它锯掉自己坐的树枝。这类操作必须由人工在终端完成。后来我在 SOUL.md 中加了铁律：禁止修改 openclaw.json，禁止尝试重启 Gateway。

🪤 坑 2：systemctl restart 杀不死子进程，端口冲突死循环

修改完 Agent 身份配置后重启 Gateway，执行 systemctl restart openclaw-gateway，结果 Gateway 启动不了了。

根因：openclaw gateway run 启动后会 fork 子进程。systemd 默认只杀主进程，子进程变成孤儿继续占着端口 18789。新进程启动→端口冲突→失败→重试→又失败→连续 5 次触发限速保护→彻底起不来。

解决方案：

kill -9 $(lsof -ti :18789) 2>/dev/null
pkill -9 -f openclaw 2>/dev/null
sleep 3
systemctl reset-failed openclaw-gateway
systemctl start openclaw-gateway

铁律：永远不要直接 systemctl restart，要用「停止→按端口杀残留→启动」三步走。

🪤 坑 3：两套 systemd 服务打架，Gateway 反复被杀

为了实现自愈，我在 /etc/systemd/system/ 创建了系统级服务。但 OpenClaw 自带的 gateway install 会在用户级 ~/.config/systemd/user/ 创建服务。两个服务同时抢端口 18789，互相杀进程，飞书 WebSocket 刚建立就断。

教训：不要自己创建系统级服务来管 OpenClaw！ 用它自带的 openclaw gateway start/stop 就好。

🪤 坑 4：改了配置，飞书里 Agent 还是旧身份

把所有配置文件里的名字都改成了「钱多多」，Gateway 也重启了，但飞书里问 Agent「你叫什么」，它还自称「多多助理」。

根因：Agent 的会话有上下文缓存。旧会话加载的是旧配置，即使 Gateway 重启了，飞书端的对话窗口可能还在旧会话里。

解决方案：在飞书里发 /reset 开新会话。这一步很容易忘，但改配置后必须做。

🪤 坑 5：Gemini 模型无视自定义 Skill，自己写代码调用 OpenAI

这是我遇到的最「魔幻」的一个坑。我给 Gemini 配了自定义画图 Skill，结果它根本不用——它通过 exec 工具自己生成了 200 多行 Python 代码，内联调用 api.openai.com（国内不可达）。

更离谱的是，我在 SOUL.md 里用 {baseDir}/scripts/generate_image.py 指定了路径，它还是不听——因为 {baseDir} 是 Skill 内部的模板变量，写在 SOUL.md 里模型看到的就是字面量，根本不解析。

最终方案（三管齐下）：

SOUL.md 中用绝对路径指定画图命令
备份禁用内置的 openai-image-gen Skill
飞书发 /new 开新会话

核心认知：强模型（Gemini、Claude）会用 exec 自己写代码执行，Skill 文件只是参考，不是约束。 要控制模型行为，必须在系统提示词中用绝对路径明确指令，同时堵死旧的干扰源。

🪤 坑 6：中转站模型名必须加特殊前缀

通过中转站 A 中转站接入 Gemini，配置中写 gemini-2.5-pro，结果 model_not_found。查了 /v1/models 接口才发现，中转站 A 的模型名全部带 [L] 前缀。

教训：接入新中转站时，第一件事查 /v1/models 接口确认实际模型名，不要假设和官方一致。

🪤 坑 7：往配置里加了个不存在的字段，Gateway 直接拒绝启动

想给 Gemini 配视觉模型，在配置里加了 visionModel 字段，结果 Gateway 报错 Config invalid: Unrecognized key。

教训：OpenClaw 有严格的配置校验，不认识的 key 直接拒绝启动。 视觉能力不需要单独配置，在 Provider 模型定义里加 input: ["text", "image"] 即可。

🪤 坑 8：余额不足不触发降级，飞书直接报错

中转站余额只剩 ¥3.825，单次请求需要 ¥7.700，API 返回 403。我以为降级链会自动切换到其他模型——并没有。降级链中配了 14 个备选，一个都没被尝试。

根因：OpenClaw 的降级链只处理 5xx 和超时。403 属于客户端错误，被视为「配置错误」，不触发降级。这个逻辑对同 Provider 内的降级是合理的（同一个 Key 余额不足，换模型也没用），但跨 Provider 降级时就失效了。

教训：如果用按量计费的中转站，务必关注余额，不要指望降级链兜底。

🪤 坑 9：/v1/models 列出 46 个模型，你的 Key 只能用其中几个

换了新中转站中转站 B，/v1/models 返回 46 个 Gemini 模型。调画图模型全部 503。逐一测试后发现只有 gemini-2.5-flash-image 能用。

根因：中转站的 API Key 有分组机制。/v1/models 返回的是平台全部模型的超集，不代表你的 Key/分组都能调用。

教训：/v1/models 列表 ≠ 你能用的模型。 必须逐一 curl 测试确认。

🪤 坑 10：换中转站后画图脚本还在读旧 Provider

从中转站 A 切到中转站 B，openclaw.json 改了，但画图还是报错。查脚本源码发现 get_config() 里硬编码了 .get("中转站 A",{})。

教训：换中转站是个系统工程。 不只是改 openclaw.json，自定义脚本里硬编码的 Provider 名称也要同步更新。建议脚本中的 Provider 名用环境变量传入，避免硬编码。

🪤 坑 11：npm 全局前缀变更——一颗静默的核弹

从 OpenClaw 2026.3.8 升级到 2026.3.23-2，升级后 openclaw 命令直接 No such file or directory。排查发现 npm 全局前缀从 /usr/lib 变成了 /usr/local/lib，三处硬编码旧路径全部失效：

bash 命令缓存
systemd 服务文件的 ExecStart
飞书插件配置的 installPath

这可能是所有坑里影响面最广的一个。 需要同时修 bash 缓存（hash -r）、systemd 路径（sed -i）、插件路径（注意新版目录结构也变了），最后重启 Gateway 验证。

教训：npm 全局前缀变更是静默的核弹。 升级后第一件事检查 npm config get prefix。

🪤 坑 12：废弃 Provider 不删，降级链里全是无效节点

先后用过 3 个中转站，每次切换只做加法不做减法。结果降级链前两位是余额已空的中转站 A，子 Agent 还指向不稳定的 [中转站 C](http://中转站 C)，看起来有 5 个 Provider，实际只有 3 个能用。

教训：切换中转站 = 新增 + 删除，缺一不可。 建议定期做配置审计，用脚本打印所有 Provider 和降级链的实际状态。

🪤 坑 13：同一中转站，画图的 Key 调不了 Claude

用中转站 B 的画图 Key（属于 优质banana 分组）去调 Claude，报错 无可用渠道。联系客服才知道，Claude 需要另一个分组的 Key。

教训：同一中转站的不同模型系列可能需要不同的 API Key 分组。 最佳实践是按模型系列申请不同 Key，在配置中注册为独立 Provider。

四、架构设计：多模型协作是怎么搭的

踩完坑之后，我最终搭建了一个相对稳定的多模型协作架构。分享一下设计思路。

4.1 模型分工

不同任务用不同模型，这是核心策略：

场景	模型	理由
日常对话	Kimi K2.5（DashScope）	国内直连最稳定，响应快
编程/写作/研究	Claude Opus 4.6（中转站 B）	强推理 + 长上下文
画图	Gemini（中转站 B）	走自定义脚本
每日推送 AI 总结	Kimi K2.5（DashScope）	成本低，够用
读图	Qwen3-VL-Plus（DashScope）	国内模型兜底

4.2 子 Agent 团队

主 Agent「钱多多」是管家，负责接收任务、判断类型、分派给 4 个子 Agent：

researcher：搜索调研，用 SearXNG + Jina Reader
coder：写代码、改脚本，指定用 Claude Opus 4.6
writer：写文章、内容创作
trader：股票分析、行情数据，用 TuShare

关键配置技巧：在子 Agent 的 AGENT.md 第一行加 model: 中转站 B/claude-opus-4-6 就能覆盖全局默认模型。这样只有 coder 走贵的 Opus，其他子 Agent 继续用便宜的 Kimi。

4.3 降级链设计

Kimi K2.5 → MiniMax M2.5 → Qwen3.5-Plus → Qwen3-Max → GLM-5 → Qwen3-Coder-Plus

全链路走 DashScope（阿里云 Coding Plan），国内直连，避免海外中转站的不确定性。记住：降级链只对 5xx 和超时生效，403 不触发降级。

4.4 记忆体系

这是 OpenClaw 2026.3.8 新框架的核心改变：

层级	文件	作用	可靠性
核心人格	SOUL.md	硬性规则、行为准则	⭐⭐⭐ 最高
身份定义	IDENTITY.md	名字、角色、风格	⭐⭐⭐
用户信息	USER.md	主人资料、历史教训	⭐⭐⭐
调度规则	AGENTS.md	子 Agent 团队调度	⭐⭐⭐
长期记忆	MEMORY.md	Agent 可读写的记忆	⭐⭐
对话记忆	当前上下文	关闭即丢失	⭐

重要变更：新版不再读取 AGENT.md，改为 SOUL.md + IDENTITY.md + USER.md 三文件。从旧版升级必须迁移，否则 Agent 会完全失忆。

五、让 AI 不再编造金融数据：我的解决方案

这是一个非常典型的 Agent 应用痛点——AI 编造数据。

问题

最初的每日推送脚本用 Qwen2.5-72B 做 AI 总结，它会凭空编造指数涨跌幅。真实数据是上证 -0.81%，它「总结」出 +0.03%，方向都反了。

解决思路

用代码获取真实数据，在 prompt 中注入，同时在系统提示词中设置多重防线。

行情数据模块（market_data.py）：东方财富 API（主）+ TuShare（备），获取真实的指数和板块数据，完全不依赖 AI
新闻采集模块（news_sources.py）：SearXNG 本地搜索 + 新浪财经直接抓取，全部免费无限额
域名白名单过滤：只保留权威财经站（新浪财经、东方财富、财联社、华尔街见闻等）的新闻，过滤百科、知乎等非新闻内容
Prompt 注入：将真实行情数据直接注入 prompt，并在指令中写死「指数数据必须原样使用，严禁修改任何数字」
**AGENT.md 防线**：在系统提示词中列举常见错误模式，逐一禁止

效果

修复后的推送流程：Python 脚本先拿到真实行情 → 搜索并过滤新闻 → 把数据和新闻一起喂给 AI → AI 只做「总结组织」不做「数据生成」 → 推送到飞书。数据终于和同花顺 App 对得上了。

六、那些「媒体不会告诉你」的事

用了一周 OpenClaw 之后，我总结了几点认知，是很多入门教程不会提的：

6.1 配置文件是一个系统工程

openclaw.json 不是改一个参数就完事。它牵连着：

模型 Provider（API Key、baseUrl、模型名）
降级链（顺序、超时策略）
子 Agent 的模型指向
飞书插件路径
自定义脚本中硬编码的 Provider 名

任何一处没改到位，都可能导致莫名其妙的报错。换中转站时建议拉个 checklist，逐项核对。

6.2 强模型不听话是常态

Gemini、Claude 这样的强模型，它们有自己的「主见」。你在 Skill 文件里写的规则，模型可能完全不看，直接用 exec 自己写代码执行。控制模型行为的最有效手段是：

在 SOUL.md 中用绝对路径指定命令
用禁止语句堵死错误路径（「严禁调用 api.openai.com」）
物理禁用干扰源（backup/rename 掉旧 Skill 脚本）

6.3 会话缓存是个隐形杀手

改了配置→重启了 Gateway→飞书测试→没变化→以为配置没生效→继续改→越改越乱。其实只是旧会话的上下文缓存了旧配置。

养成习惯：改完配置，飞书里先发 /reset 再测试。

6.4 日志是你最好的朋友

很多问题光看飞书端的报错信息是定位不了的。必须去看 Gateway 日志：

tail -f /tmp/openclaw/openclaw-$(date +%Y-%m-%d).log

模型选择、降级触发、Skill 调用、错误详情，都在日志里。

6.5 备份！备份！备份！

我有一次备份翻车，导致 4 个子 Agent 全部丢失，花了 5 个小时才恢复。后来专门写了全盘备份脚本和一键恢复方案。

每次大改配置前：

cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak.$(date +%Y%m%d%H%M)

这一行命令，能在关键时刻救你的命。

七、一些实用的调试技巧

分享几个我反复用到的调试命令和方法：

7.1 升级后的检查清单

hash -r                         # 刷新 bash 命令缓存
which openclaw                  # 确认二进制位置
npm config get prefix           # 检查 npm 全局前缀
openclaw gateway status         # 检查服务状态
grep installPath ~/.openclaw/openclaw.json  # 检查插件路径

7.2 安全重启 Gateway

kill -9 $(lsof -ti :18789) 2>/dev/null
pkill -9 -f openclaw 2>/dev/null
sleep 3
systemctl reset-failed openclaw-gateway 2>/dev/null
openclaw gateway start
sleep 5
openclaw gateway status

7.3 批量测试中转站模型

for m in "model-name-1" "model-name-2" "model-name-3"; do
  echo -n "Testing $m: "
  curl -s $BASE_URL/v1/chat/completions \\
    -H "Authorization: Bearer $API_KEY" \\
    -d "{\\"model\\":\\"$m\\",\\"messages\\":[{\\"role\\":\\"user\\",\\"content\\":\\"say hi\\"}],\\"max_tokens\\":10}" \\
    --max-time 15 | python3 -c "
import sys,json
r=json.load(sys.stdin)
print('OK!' if 'choices' in r else r.get('error',{}).get('message','')[:80])"
done

7.4 配置审计脚本

python3 -c "
import json
c = json.load(open('/root/.openclaw/openclaw.json'))
print('=== Provider 列表 ===')
for name, p in c['models']['providers'].items():
    key = p.get('apiKey', '')[:8] + '****'
    models = [m['id'] for m in p.get('models', [])]
    print(f'  {name}: {len(models)} 模型, Key: {key}')
print(f'\\n=== 降级链 ===')
for i, m in enumerate(c['agents']['defaults'].get('models', {}).keys(), 1):
    print(f'  {i}. {m}')
"

八、我的配置文件结构（供参考）

经过一周的迭代，我的 OpenClaw 工作区结构如下：

~/.openclaw/
├── openclaw.json              ← 全局配置（模型、API Key、环境变量）
└── workspace/
    ├── SOUL.md                ← 核心人格规则（硬性规则）
    ├── IDENTITY.md            ← 身份定义
    ├── USER.md                ← 用户信息
    ├── AGENTS.md              ← 子 Agent 调度规则
    ├── MEMORY.md              ← Agent 长期记忆
    ├── scripts/
    │   ├── a-stock-daily-push.py  ← 每日推送脚本
    │   ├── market_data.py         ← 行情数据模块
    │   ├── news_sources.py        ← 新闻采集模块
    │   └── run_daily_trading.py   ← 交易脚本
    ├── holdings/              ← 持仓数据
    └── logs/                  ← 日志

每个 .md 文件都有明确的职责分工，不要把所有规则都堆在一个文件里。