openclaw + 飞书机器人踩坑记录

问题总结

问题 1：飞书机器人无法回复消息

症状：

• 飞书能收到消息（WebSocket 连接正常）
• 但消息没有触发 Agent 处理
• Agent 无响应

原因：

• 飞书插件未正确安装
• 配置路径不匹配：配置中 installPath 为 ~/.openclaw/extensions/feishu，但实际插件安装在 /usr/lib/node_modules/@openclaw/feishu/

解决方案：

# 1. 使用 sudo 安装插件到全局 node_modules
sudo npm install -g @openclaw/feishu
 
# 2. 重启 OpenClaw 网关
openclaw gateway restart

---

问题 2：消息无法触发 Agent 处理（权限问题）

症状：

• 飞书收到消息
• 但没有触发 Agent run
• 日志中没有 “embedded run start” 记录

原因：

• dmPolicy 配置为 "allowlist"（白名单模式）
• 消息发送者的 ID 不在白名单中
• 虽然 WebSocket 接收到了消息，但由于 DM 策略检查，没有传递给 Agent

解决方案：

# 修改配置文件 ~/.openclaw/openclaw.json
# 将 dmPolicy 从 "allowlist" 改为 "open"（开放模式）
 
{
  "channels": {
    "feishu": {
      "enabled": true,
      "appId": "cli_a9da4baa1fa2dbc9",
      "appSecret": "xxx",
      "dmPolicy": "open",  // 改为 open
      "domain": "feishu"
    }
  }
}

---

问题 3：飞书消息出现在 Web UI 中

症状：

• 在飞书中发送消息
• 消息会同步显示在 OpenClaw Web UI 的对话历史中

原因：

• 这是 OpenClaw 的单一会话模式（Single Session）设计
• 飞书、Web UI、Slack 等所有消息渠道共享同一个会话（agent:main:main）
• 消息流：飞书 → Agent 处理 → 更新共享会话历史 → Web UI 显示完整对话

机制说明：

• 优点：
• 跨渠道对话连贯性：在飞书问的问题，可以在 Web UI 看到答案
• Token 节省：共享上下文，不会重复存储对话历史
• 统一管理：所有渠道的对话历史集中在一个会话中
• 排队机制：
• 单一会话 = 单线程处理
• 当 Agent 正在处理复杂查询（比如 40 秒）时，后续消息会排队等待
• 这是为了保证对话顺序不混乱，防止消息丢失

如何避免消息出现在 Web UI？ 如果你希望飞书和 Web UI 的对话完全隔离，需要：

1. 启用多会话模式（需要修改 Agent 配置）
2. 或者为不同渠道配置独立的会话
3. 但默认的单一会话模式通常更有用，因为它提供了跨渠道的对话连贯性

---

OpenClaw 会话管理

会话相关命令

# 1. 列出所有会话
openclaw sessions list
 
# 2. 查看会话详情
openclaw sessions inspect agent:main:main
 
# 3. 删除会话（清空上下文）
openclaw sessions delete agent:main:main
 
# 4. 创建新会话（用于隔离对话）
openclaw sessions create
 
# 5. 压缩会话（减少 Token 使用）
openclaw sessions compact agent:main:main
 
# 6. 导出会话历史
openclaw sessions export agent:main:main > history-backup.json

会话文件位置

• 会话存储：~/.openclaw/agents/main/sessions/sessions.json
• 会话文件：~/.openclaw/agents/main/sessions/c7d5a6b5-fbf1-4192-b265-dcff96141674.jsonl

---

飞书配置说明

DM 策略对比

策略	说明	适用场景
open	开放模式，所有消息都会触发 Agent	个人机器人，所有用户都能使用
allowlist	白名单模式，只处理白名单中的用户消息	多用户机器人，需要控制访问权限
pairing	配对模式，需要先配对才能使用	临时授权场景

推荐配置

{
  "channels": {
    "feishu": {
      "enabled": true,
      "appId": "your_app_id",
      "appSecret": "your_app_secret",
      "dmPolicy": "open",
      "domain": "feishu"
    }
  }
}

---

最佳实践

1. 插件安装：使用 sudo npm install -g @openclaw/feishu 确保插件安装在全局 node_modules
2. 权限配置：个人机器人使用 dmPolicy: "open"，避免权限问题
3. 会话管理：定期执行 openclaw sessions compact 压缩会话，减少 Token 使用
4. Token 监控：使用 openclaw sessions inspect 监控 Token 使用，避免超出限制

---

常见错误

错误 1：Unknown target for Feishu

原因： 发送消息时目标 ID 格式不正确 解决： 确保使用正确的 ID 格式（open_id、union_id 或 chat_id）

错误 2：Failed to create streaming card: Access denied

原因： 缺少飞书 API 权限 cardkit:card:write 解决： 在飞书开发者后台开通相应权限

错误 3：session file locked

原因： 会话文件被锁定，可能是进程卡死 解决： 删除会话锁文件或重启 OpenClaw 网关

---

🔗 相关资源

• OpenClaw 文档
• 飞书开放平台
• OpenClaw 故障排查