OpenClaw 架构与组件说明

OpenClaw 架构与组件说明

概述

说明 OpenClaw 的主要组件、职责、数据流、运维要点、常见故障与排查，以及扩展建议。适合作为运维与开发参考。

目录

1. TL;DR
2. 组件清单与职责
3. 数据流与调用序列（示例）
4. 部署与运维注意点（命令示例）
5. 常见故障场景与排查要点
6. 详细 Mermaid 架构图
7. 后续可选扩展与建议

1. TL;DR

• Gateway 是运行时中枢，负责接收外部事件、路由到 agent、管理 cron/heartbeat 并投递结果。
• Channels/Adapters 对接外部平台（Feishu/QQ/Telegram 等），负责事件标准化与消息格式化。
• Scheduler 提供 cron/heartbeat 调度，cron 用于精确时间点触发，heartbeat 用于短周期巡检（在 main session 中运行）。
• Agents 分 main（有长期记忆权限）与 isolated（隔离执行）; Skills 为可复用工具/脚本。
• 配置/记忆/脚本保存在 workspace（/root/.openclaw/workspace）与 openclaw.json。

2. 组件清单与职责（详述）

A. Gateway（运行时中枢）

• 核心职责：
  • 接受外部事件（Webhook / WebSocket / Polling），把事件转为内部消息。
  • 调度 cron / heartbeat；触发 agentTurn / systemEvent。
  • 路由 agent 响应到正确 channel（reply、announce、direct send）。
  • 管理 session（main / isolated）、子 agent 的创建与回收。
• 常见实现细节：
  • 提供 RPC（gateway.remote.url + token）供 CLI 与外部管理；提供 openclaw gateway start/stop/restart/status。
• 运维关注点：
  • 配置保存在 /root/.openclaw/openclaw.json；修改后通常需要 restart。
  • 若使用 WebSocket，与平台的长连接需监控重连与心跳。

B. Channels / Adapters

• 包括：Feishu、QQ、Telegram、WeCom、DingTalk、Email 等。
• 职责：
  • 将渠道消息标准化成内部事件模型（sender、chat_id、open_id、text、attachments）。
  • 将内部回复格式转换为平台特定格式（markdown → Feishu card、富文本等）。
• 要点：
  • 每个 channel 需要凭证（appId/appSecret、token）；权限 scope（如 Feishu 的 cardkit:card:write）可能限制某些功能。
  • 支持目标 "last"（发送到最近互动的会话）与显式 open_id 发送。

C. Scheduler（cron / heartbeat）

• cron：支持 cron 表达式、every（间隔）、at（一次性）。payload 可以是 agentTurn 或 systemEvent；可指定 sessionTarget（isolated / main）与 delivery（announce）。
• heartbeat：全局周期性唤醒 main session，常用于短周期巡检（如每 5/15 分钟）；因运行在 main，会访问 MEMORY.md / workspace 等敏感资源。
• 管理命令/位置：heartbeat 全局配置在 openclaw.json（agents.defaults.heartbeat.every）；cron 任务通过 cron.add / cron.list / cron.run / cron.remove 管理。

D. Agents & Sessions

• main session：拥有长期记忆权限（MEMORY.md），用于交互与需要上下文的任务。
• isolated session：隔离执行，适合长耗时或高风险任务，避免污染 main 会话。
• 子 agent：用于并行任务与后台运行。
• 模型调用与资源限制：注意 agents.defaults.maxConcurrent 等配置以避免并发过高。

E. Skills / Tools

• 本地 skill（Python/Node 脚本）、外部 API 封装（Tushare、Open-Meteo、Serper、Agent Browser）等。
• 职责：提供可复用的操作（股票抓取、天气、caldav、浏览器自动化）。
• 位置：/root/.openclaw/workspace/skills/

F. Storage / Workspace / Memory

• openclaw.json（全局配置）
• workspace（skills、HEARTBEAT.md、TODO.md、scripts）
• MEMORY.md（长期记忆，仅 main session 可读）
• cron state / heartbeat-state.json（记录 last checks）
• 建议备份：/root/backups/openclaw-YYYYMMDD.tgz

G. Delivery & Formatting

• 格式：plain text、markdown → 转换器 → 平台 card / rich text
• Delivery 模式：announce（主动发到 channel）、reply（回复来源）、none（不外发，仅运行）
• 处理附件上传（图片/CSV）与限速

H. Monitoring / Logging

• 常用命令：openclaw logs --limit N --plain；--follow 实时跟随。
• 关注点：WS 连接、权限错误（scope）、cron 执行失败、skill 异常。
• 建议：对关键错误建告警并设置自动重试或降级策略。

I. Security / Auth

• 存储凭证需限权并备份；不要在公开渠道粘贴。
• RPC token 控制远程管理访问；渠道 scope 需在平台控制台申请。

3. 数据流与调用序列（示例：Feishu 私信触发股票摘要）

1. 用户 → Feishu 发送消息（Webhook 或 WebSocket event）
2. Feishu adapter 接收事件并转换为内部事件（含 sender.open_id / chat_id / text）
3. Gateway 将事件推入 agents，选择 main session（或 spawn isolated）
4. Agent 调用 skill（stock-watcher / stock-analysis）；skill 从数据源（Tushare / Yahoo / 通达信 API）拉取行情
5. skill 返回结构化结果给 agent；agent 生成回复（模型或模板）
6. Delivery 层格式化并由 channel adapter 发回 Feishu（可能上传附件）
7. Gateway 记录日志并更新 memory/cron state（如需要）

4. 部署与运维注意点（命令示例）

• 查看版本：
  openclaw --version
• Gateway 状态：
  openclaw gateway status
• 启动/停止/重启：
  openclaw gateway start|stop|restart
• 日志：
  openclaw logs --limit 200 --plain
  openclaw logs --follow
• 列出 cron：
  openclaw cron list （或使用 cron.list 工具）
• 修改心跳：
  编辑 /root/.openclaw/openclaw.json agents.defaults.heartbeat.every 后重启 gateway
• 备份示例：
  mkdir -p /root/backups/openclaw-(date+cp/root/.openclaw/openclaw.json/root/backups/openclaw−(date +%F_%T) cp /root/.openclaw/openclaw.json /root/backups/openclaw-(date+cp/root/.openclaw/openclaw.json/root/backups/openclaw−(date +%F_%T)/
  tar -czf /root/backups/openclaw-workspace-$(date +%F).tgz /root/.openclaw/workspace

5. 常见故障场景与排查要点

• 场景：Feishu 收到消息但机器人不回

  • 检查：openclaw logs（feishu-monitor / feishu-message）→ 是否收到 event？是否有权限错误（如 cardkit:card:write）？
  • 操作：确认 appId/appSecret、开发者控制台事件订阅与 scope

• 场景：cron 未触发

  • 检查：cron.list → nextRunAtMs；openclaw logs 查看 scheduler 错误
  • 操作：确认 cron 表达式、时区（tz）与 gateway 时间同步

• 场景：skill 运行时报错或超时

  • 检查：skill stderr/stacktrace（logs）与依赖是否安装
  • 操作：在 workspace 手动运行脚本调试；增加重试或降级策略

• 场景：长耗时 agent 导致主会话阻塞

  • 建议：将耗时任务放到 isolated / spawn 子 agent，或使用独立 worker

6. 详细 Mermaid 架构图（供复制渲染）

Storage / Workspace
Gateway (OpenClaw)
外部平台 / 数据源
events/ws/webhook
events
events
normalized event
fetch
fetch
fetch
search
trigger
result
alerts
metrics
Feishu
QQ
Telegram
WeCom
通达信 API / 第三方行情
Tushare / A股 数据
YFinance / 美股 港股
Serper / 搜索
Channels / Adapters
Auth / Scopes
Scheduler (cron / heartbeat)
Agents & Sessions\nmain / isolated
Skills / Tools
Delivery & Formatter
Logging & Monitoring
openclaw.json
MEMORY.md & workspace
cron state / heartbeat-state.json
skills scripts & assets
Monitoring System

7. 后续可选扩展与建议

• 将行情持久化到时序 DB（InfluxDB / TimescaleDB），支持回测与高频指标。
• 将高频监控（每分钟）放到独立 worker 集群，gateway 仅做路由和调度。
• 若能取得通达信 API，优先拉取通达信的指标输出，减少重复实现；否则把通达信公式转为 Python 在服务器上计算。
• 容器化 + 蓝绿/滚动升级以减少中断，重要节点做快照/备份以支持回滚。