OpenClaw安全防护手册：攻击方式与保护指南

全面的OpenClaw安全防护指南，详细解析各种攻击方式包括提示词注入、权限滥用、数据泄露等，提供全面的防护策略和最佳安全实践。

---

背景

杰斯（Jayce）是基于 OpenClaw 框架搭建的 AI Agent，目标是：

• 在 macOS 上 24/7 后台运行（通过 launchd 守护进程）
• 通过 飞书 WebSocket 接收消息并回复
• 支持按需切换 DeepSeek / Gemini / Claude / Moonshot 等多个模型
• 扩展为多 Agent 团队协作（唐玄宗、朱元璋、锦衣卫、达芬奇）

---

2026-03-08｜部署首日：首次启动、模型配置与工具调通

问题一：首次启动 UI 编译，长时间无响应

现象：

Gateway 启动后约 70 秒内飞书毫无回应，以为挂了。

日志证据：

2026-03-08T01:48:18 [gateway] Control UI assets missing; building (ui:build, auto-installs UI deps)…
2026-03-08T01:48:25 [gateway] listening on ws://127.0.0.1:18789 (PID 70163)

从触发 ui:build 到实际监听，共约 7 秒（本机性能较好），但首次含依赖安装可能更长。

解决方案：

等待 UI 编译完成，看到 ws client ready 后再发消息，不要重复重启。

---

问题二：多次修改模型配置导致频繁重启

现象：

用户陆续为杰斯添加了多组模型（Anthropic / DeepSeek / Gemini），每次保存 openclaw.json 都触发一次 Gateway 重启（SIGTERM）。

日志证据：

02:15:29 [reload] config hot reload applied (agents.defaults.model, agents.defaults.compaction)
02:22:22 [gateway] signal SIGTERM received; shutting down
02:36:55 [reload] config hot reload applied (models.google/gemini-2.5-pro, gemini-2.5-flash…)
02:43:45 [gateway] signal SIGTERM received; shutting down

解决方案：

建议将所有模型一次性写好后再保存，避免多次触发热重载。OpenClaw 支持配置热重载，但频繁重启会中断正在进行的对话。

---

问题三：浏览器截图工具调通（typing TTL 超时）

现象：

用户要求「打开浏览器截图 apple.com」，杰斯 2 分钟内无回复，日志显示 typing TTL reached，但浏览器进程已正常启动。

日志证据：

02:43:04 DM: [示例：用户要求执行需要登录验证的操作]
02:44:37 DM: [示例：用户重复发送相同指令]
03:00:22 DM: 浏览 clawhub.com，给你自己装一个多平台资讯抓取的 skill
03:13:00 typing TTL reached (2m)

原因：

部分网站（微信网页版、推特/X）有登录验证和反 bot 机制，浏览器控制工具无法直接操作。

解决方案：

需要预先登录相关网站的 Chrome profile，或使用支持鉴权的 API 接口方式替代浏览器操控。

---

问题四：Skill 安装（clawhub）命令找不到

现象：

用户要求杰斯「浏览 clawhub.com，自己装股票分析 skill」，杰斯尝试运行 clawhub search <技能名> 失败。

原因：

clawhub 是 OpenClaw 生态的 Skill 包管理工具，需要先手动安装，杰斯的 shell 环境中未配置。

解决方案：

按照 clawhub 文档手动安装 CLI，或直接将 skill 配置写入 openclaw.json 的 plugins.entries。

---

2026-03-09｜浏览器功能调试与 SystemPrompt 更新

问题五：浏览器截图任务超时，Gateway 触发 SIGUSR1 重启

现象：

03-09 凌晨，用户再次要求「打开浏览器截图 apple.com」，杰斯 2 分钟无响应，且本次触发了 SIGUSR1（热重启信号）。

日志证据：

2026-03-09T00:26:17 DM: 打开浏览器截图 apple.com
2026-03-09T00:28:17 typing TTL reached (2m); stopping typing indicator
2026-03-09T00:29:37 [gateway] signal SIGUSR1 received; restarting
2026-03-09T00:29:37 [gateway] draining 2 active task(s) before restart (timeout 30000ms)

原因：

任务超时后 Gateway 收到外部 SIGUSR1，执行优雅重启（先等待活跃任务完成再重启），与 SIGTERM 强制关闭不同。

解决方案：

确认浏览器 Chrome profile 已完成 apple.com 的证书信任，或改用 web_fetch 替代浏览器截图。

---

问题六：SystemPrompt 更新触发飞书频道重连

现象：

修改 channels.feishu.systemPrompt 后，飞书频道断开并重新连接，期间约 1 秒内无法收发消息。

日志证据：

2026-03-09T00:29:18 [reload] config change detected; evaluating reload (channels.feishu.systemPrompt)
2026-03-09T00:29:18 [gateway/channels] restarting feishu channel
2026-03-09T00:29:18 [feishu] feishu[default]: abort signal received, stopping
2026-03-09T00:29:18 [reload] config hot reload applied (channels.feishu.systemPrompt)

结论：

修改 systemPrompt 属于频道级热重载，会导致 WebSocket 短暂断开，属正常行为。修改后等待 ws client ready 出现即可。

---

2026-03-10｜多 Agent 团队上线与多重故障

问题七：openclaw 命令不存在，版本更新失败

现象：

用户让杰斯「把自己的 openclaw 版本更新一下」，杰斯执行 openclaw update 报错。

日志证据：

2026-03-10T21:48:42 DM: 把你自己的版本更新一下（openclaw版本）
2026-03-10T21:48:45 [tools] exec failed: zsh:1: command not found: openclaw

原因：

OpenClaw Gateway 是通过源码启动（~/path/to/openclaw/project/），并没有全局安装 openclaw CLI 命令，因此 shell 中找不到该命令。

解决方案：

更新方式应为：

cd ~/path/to/openclaw/project/
git pull
npm install
launchctl kickstart -k gui/$(id -u)/com.openclaw.gateway

---

问题八：添加 Moonshot Provider 后 Token Mismatch

现象：

添加唐玄宗（moonshot 模型）配置并重启后，OpenClaw Mac 客户端显示 gateway token mismatch，无法连接。

日志证据：

2026-03-10T22:27:49 [reload] config hot reload applied (models.providers.moonshot, agents.list…)
2026-03-10T22:35:58 [gateway] signal SIGTERM received; shutting down
2026-03-10T22:40:33 [gateway/ws] unauthorized: token mismatch
2026-03-10T22:40:33 [gateway] connect failed: unauthorized - gateway token mismatch

原因：

Gateway 重启后会生成新的连接 Token，但 OpenClaw Mac 菜单栏客户端缓存了旧 Token，导致鉴权失败。

解决方案：

重启 OpenClaw Mac 菜单栏应用，让客户端重新握手获取新 Token：

菜单栏 → OpenClaw 图标 → Quit → 重新打开

---

问题九：Gemini API 503 + web_search 工具失败

现象：

杰斯在执行长任务（整理博文内容）时，web_search 工具连续失败。

日志证据：

2026-03-10T22:50:36 [tools] web_search failed: fetch failed
2026-03-10T22:51:12 [tools] web_search failed: Gemini API error (503)

原因：

Gemini 作为搜索后端出现服务不可用（503），可能是 Google API 短暂故障或达到调用频率限制。

解决方案：

配置备用搜索工具（如 ddgr 本地搜索），或切换 web_search 工具的后端为不依赖 Gemini 的方案。

---

问题十：长任务超时（10 分钟 embedded run timeout）

现象：

杰斯执行「整理 openclaw 部署问题做博文」等长任务时，触发 10 分钟超时，任务失败。

日志证据：

2026-03-10T22:58:10 [warn] embedded run timeout: 600000ms (sessionId=917cf...)
2026-03-10T22:58:10 [warn] embedded run failover decision: surface_error (timeout)

解决方案：

将大任务拆解为子任务分步执行，避免单个任务超过 10 分钟限制。或在 openclaw.json 中调大 agents.defaults.timeout 参数。

---

2026-03-11｜PM2 与 launchd 冲突导致端口战争

这是部署以来最严重的一次故障，Gateway 陷入循环崩溃，272 次启动失败。

问题十一：PM2 与 launchd 双进程管理器冲突

背景：

用户希望通过朱元璋 Agent 安装 PM2 来管理进程，并让朱元璋创建 ecosystem.config.js 启动 Jayce-Gateway。

时间线：

10:08 DM: 学习运维技能（gateway_manager，含 pm2 重启命令）
10:16 DM: 朱元璋，检测电脑上是否安装了 pm2，没有的话 npm 全局安装
10:22 DM: 如果有 brew，直接 brew install pm2
10:33 DM: 创建 ecosystem.config.js，配置 Jayce-Gateway 进程，用 pm2 启动
10:36 [gateway] signal SIGTERM received; shutting down  ← Gateway 被 PM2 接管后重启

根本问题：

此时系统同时有两个进程管理器在管理 Gateway：

• launchd：com.openclaw.gateway（系统级守护进程，随系统自动启动）
• PM2：Jayce-Gateway（用户安装，pm2 start ecosystem.config.js）

两者都在监听 127.0.0.1:18789，导致端口冲突循环崩溃。

灾难现场（03-11 深夜）：

23:25:37 [CRITICAL] gateway already running (pid 13667); lock timeout 5000ms
23:25:37 [CRITICAL] Port 18789 is already in use
23:27:41 [ERROR] Port 18789 already in use (pid 20890)
... (以上错误重复出现 272 次，持续至 23:59)

解决方案：

二选一，不能共存：

方案 A：继续用 launchd（推荐）

# 停止并卸载 PM2 管理的 Gateway
pm2 delete Jayce-Gateway
pm2 save

# 确认 launchd 正常工作
launchctl kickstart -k gui/$(id -u)/com.openclaw.gateway

方案 B：切换到 PM2

# 先卸载 launchd 服务
launchctl unload ~/Library/LaunchAgents/com.openclaw.gateway.plist

# 用 PM2 接管
pm2 start ecosystem.config.js
pm2 save
pm2 startup   # 配置开机自启

教训： 进程管理器只能选一个。launchd 是 macOS 原生方案，稳定性更好；PM2 适合 Node.js 生态，可视化更友好，但不能与 launchd 同时管理同一服务。

---

问题十二：Memory 文件找不到（ENOENT）+ Gemini Embeddings 限额

现象：

早晨杰斯启动后，日志报大量 memory 文件读取失败和 embeddings 限额错误。

日志证据：

2026-03-11T08:29:15 [tools] read failed: ENOENT: no such file or directory '/Users/zhangtao/.openclaw/workspace/memory/2026-03-11.md'
2026-03-11T08:29:22 [warn] memory embeddings rate limited; retrying in 596ms
2026-03-11T08:31:48 [tools] read failed: EISDIR - is a directory (不能把目录当文件读)

原因：

1. Memory 文件是按日期生成的，当天首次启动时文件尚不存在，属正常现象
2. Gemini embeddings API 429（RESOURCE_EXHAUSTED）：免费额度的向量嵌入 API 有速率限制，内存同步时触发
3. EISDIR 错误：某处代码将目录路径误当文件路径传入 read 工具

解决方案：

• Memory 文件报错可忽略（首次访问自动创建）
• Gemini embeddings 限额：考虑使用 DeepSeek 或本地 Embedding 方案替代

---

问题十三：jiesi.wiki 博客部署（Vercel）

现象：

朱元璋执行博文部署任务时，因路径问题和 Vercel CLI 调用方式报错。

日志证据：

2026-03-11T08:37:14 DM: 不需要 GitHub，直接用 exec 在本机跑：
   cd /Users/zhangtao/.openclaw/workspace/jayce-home && npx vercel --prod
2026-03-11T08:40:31 DM: 以后部署只需要在项目目录执行 npx vercel --prod，不需要其他参数
2026-03-11T08:54:05 DM: [发送语音文件，持续 4 秒]

解决方案（用户指导）：

cd /path/to/project/directory
npx vercel --prod

Vercel 账号已预先登录，无需额外参数。以后所有前端部署都用这一条命令。

---

最终架构总览

macOS launchd (com.openclaw.gateway)  ← 唯一进程管理器
    └── OpenClaw Gateway (ws://127.0.0.1:18789)
            ├── 飞书 WebSocket 长连接
            ├── 杰斯 (jayce) — deepseek — ~/.openclaw/workspace/
            ├── 唐玄宗 (tangxuanzong) — moonshot-v1-32k
            ├── 朱元璋 (zhuyuanzhang) — deepseek（负责运维/成长）
            ├── 锦衣卫 (jinyiwei) — deepseek
            └── 达芬奇 (davinci) — deepseek

---

常用运维命令

# 查看 Gateway 状态
launchctl print gui/$(id -u)/com.openclaw.gateway

# 重启 Gateway
launchctl kickstart -k gui/$(id -u)/com.openclaw.gateway

# 停止 Gateway
launchctl stop com.openclaw.gateway

# 实时查看日志
tail -f ~/Library/Logs/openclaw-gateway.log

# 查看今天的详细日志
cat /tmp/openclaw/openclaw-$(date +%Y-%m-%d).log | grep -E "ERROR|WARN|DM from"

---

踩坑汇总

日期	问题	解决方案
03-08	Gateway 首次启动编译 UI，长时间无响应	等 ws client ready 出现，勿重启
03-08	模型配置多次保存触发频繁重启	一次性写好配置再保存
03-08	微信/X 浏览器操控失败	需预先登录 Chrome profile
03-08	clawhub CLI 未安装	手动安装或直接写入 plugins 配置
03-09	浏览器截图任务 2 分钟超时	调试浏览器连接，或用 web_fetch 替代
03-09	修改 systemPrompt 导致飞书短暂断连	正常热重载行为，等待重连即可
03-10	openclaw 命令找不到	通过 git pull + npm install 更新
03-10	添加 Moonshot 后 token mismatch	重启 OpenClaw Mac 菜单栏应用
03-10	Gemini API 503，web_search 失败	配置 ddgr 本地搜索作为备用
03-10	长任务 10 分钟超时	拆分子任务，或调大 timeout 参数
03-11	PM2 + launchd 同时管理 Gateway，端口冲突 272 次	二选一，删除 PM2 的 Gateway 进程
03-11	Memory 文件 ENOENT + Gemini embeddings 429	首次启动正常，限额问题考虑换 embedding 方案
03-11	Vercel 部署 jiesi.wiki 路径错误	cd 项目目录 && npx vercel --prod

最大的教训： 不要让两个进程管理器同时接管同一个服务。PM2 和 launchd 各有优势，但必须二选一——这次「PM2 vs launchd 端口战争」导致的 272 次崩溃，是整个部署过程中最惨烈的一次事故。