一、系统总览
🗺️ 全系统架构(一张图看懂)
›物理与服务拓扑
┌────────────────────── Chuck 手机/电脑上的飞书 ──────────────────────┐
│ │
│ [主号 MINISO管家] [中阿] [中英] [备忘录] [任务] [文字润色] │
│ │ │ │ │ │ │ │
└───────┼────────────┼───────┼────────┼─────────┼─────────┼──────────┘
│ │ │ │ │ │
│ Feishu Open Platform (WebSocket 长连,每个 app 一条) │
│ │ │ │ │ │
┌───────┼────────────┼───────┼────────┼─────────┼─────────┼──────────┐
│ ▼ ▼ ▼ ▼ ▼ ▼ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ feishu-bridge (launchd: com.openclaw.feishu-bridge) │ │
│ │ bridge.mjs 主进程 → fork() 6 个 worker,每 bot 一个 │ │
│ │ 白名单:CHUCK_UNION_ID (on_...) / 群聊仅 @ 响应 │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │ │
│ │ askClawdbot() WebSocket │
│ │ v3 device payload + ed25519 signature │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ OpenClaw Gateway (launchd: ai.openclaw.gateway) :18789 │ │
│ │ 统一 agent 编排:6 个 agent 不同 workspace / model / │ │
│ │ systemPromptOverride,共享 browser CDP(:18800) / web_fetch │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │ │ │ │
│ main/memo↓ 3 翻译 bot↓ task↓ │
│ Anthropic OpenAI Anthropic │
│ opus-4-6 gpt-5.1 opus-4-6 │
│ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ Cron Scheduler (gateway 内置,jobs.json 持久化) │ │
│ │ 10 个任务:7 个 Cairo TZ,3 个未显式声明 TZ (用系统) │ │
│ │ sessionTarget=isolated(每次新 session,独立 context) │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │
│ 依赖的外部:Anthropic API / OpenAI API / 飞书 OpenAPI │
│ 依赖的文件:tasks.jsonl / events.jsonl / messages.jsonl │
│ people.json / stores.json / chuck_open_id.txt │
│ chuck_union_id.txt / feishu-user-token.json │
└────────────────────────────────────────────────────────────────────┘
关键事实(纠错自 memory)
- 不是命令前缀路由:
1 个飞书 bot = 1 个 agent = 1 个 app_id,Chuck 点哪个 bot 就走哪个 agent,没有 /翻译 这种前缀。 - 所有 cron agentId 都是
task,只有一个例外:distill_main必须用main(因为要蒸馏到 main 的 MEMORY.md)。之前 memory 写 daily_report agent=main 是错的。 - translate/polish 三个 bot 真走 OpenAI gpt-5.1(不是 Claude):openclaw.json 里
model: openai/gpt-5.1+systemPromptOverride完全绕过 workspace 注入。 - main 跑 Opus 4.6 不是 4.7(openclaw 2026.4.15 provider 清单没有 4.7)。
- skill_zh_sync 是每周一 07:15(Cairo),不是每天。
- distill_main 是唯一 agent=main 的 cron;它 23:30 启动,timeoutSeconds 未声明,用 gateway 默认。
二、用户触发(Chuck 在飞书里发消息)
🤖
main bot · Chuck 的 AI 管家
✓ 在线
›
主流程(文本消息,正常路径)
Chuck 飞书发消息任意文本
→
Feishu WS 推到 bridgep2p_chat_create / im.message.receive_v1
→
union_id 白名单校验非 Chuck 静默丢弃
→
msg_type 路由text / image / post / audio
→
askClawdbot WSgateway:18789, device sig
→
main agent 处理共享 memory / 25 工具
→
CardKit 流式推送print_step=2, 40ms
→
消息到 Chuck 飞书
append daily memory~/.openclaw/workspace/memory/YYYY-MM-DD.md
特殊触发(main 独有)
Chuck 说 "扫描工作进度 [N]"bridge.mjs:660 正则
→
bridge fork 子进程node feishu-scan.mjs --days N --extract-tasks --extract-events --deliver-chuck
→
读 Chuck user_access_token~/.clawdbot/feishu-user-token.json
→
增量拉消息按 watermark 过滤已归档
→
写 tasks.jsonl + events.jsonl
→
main 发摘要到飞书
Chuck 说 "完结 T-2026-0001"bridge.mjs:611 正则
→
bridge 直改 tasks.jsonl不走 agent,直接文件写
→
status = "已完成"append progress_log
→
回 "✅ 已关闭 T-..."
Chuck 发图片msg_type=image
→
bridge 下图Feishu resources API
→
附到 askClawdbotbase64 传 Anthropic vision
→
main 读图 + 回复
Chuck 发语音msg_type=audio (OGG)
→
bridge 下音频
→
OpenAI Whisper-1 转文字STT,~$0.006/分钟
→
按文本流程处理
→
main 文字回复
异常路径(每步可能出错)
❌ bridge 进程挂了 / Gateway 断线
飞书消息根本不会被接收(没有重试,丢消息)。Chuck 发完没人回。
回复机制:launchd 自动拉起 bridge;gateway 也是 launchd 守护。通常 3-5 秒内恢复。但这 3-5 秒的消息会丢(飞书不重投)。
❌ askClawdbot 超时 / 断开
bridge.mjs 有重连逻辑,但当前 turn 会回错误卡片给 Chuck。
Chuck 重发消息即可(每条都新 session turn)。
❌ Anthropic API 超时(最常见)
main 调 opus-4-6,复杂任务可能 60s 无响应。CardKit 卡在"处理中..."。
gateway 有 per-turn timeout;超时后返回错误 text。Chuck 往往再 @ 一次就好。
❌ audio 走 Whisper 时 OPENAI_API_KEY 缺失
bridge.mjs:111 提示"voice messages will be rejected"。Chuck 发语音回 "(语音下载失败)"。
需检查
~/.clawdbot/secrets/openai_api_key。⚠️ 群聊没 @ 却触发
bridge.mjs shouldRespondInGroup() 保护。未 @ 则静默不处理,避免群聊炸。
这是设计行为,不是 bug。
依赖
Feishu OpenAPI
Feishu WS(6 长连)
Anthropic API (opus-4-6)
OpenAI Whisper-1
OpenClaw Gateway :18789
~/.openclaw/workspace
shared-memory symlink
tasks.jsonl / events.jsonl
Chuck 唯一入口
源码:
bridge.mjs:516(msg_type 路由)· bridge.mjs:611(完结触发)· bridge.mjs:660(扫描触发)·
feishu-scan.mjs:64(增量水位线)
🔤
zh_ar bot · 中→阿拉伯语翻译
✓ 在线
›
主流程
Chuck 点 zh_ar bot 发中文
→
bridge 转发agent:zh_ar:feishu:chatId:uuid(每次新 session)
→
gateway 调 OpenAIopenai-responses API + reasoning_effort
→
systemPromptOverride 生效绕过 workspace、纯 prompt
→
返回阿拉伯文
异常路径
❌ OpenAI API 429/超时
gateway 返回错误卡,Chuck 看到的是中文错误提示。
Chuck 重发即可。零上下文意味着无副作用。
❌ OPENAI_API_KEY 未设置 / 过期
gateway 直接报错。
改
~/.clawdbot/secrets/openai_api_key,无需重启(gateway 每 turn 读)。依赖
OpenAI API (gpt-5.1)
systemPromptOverride 注入
tools.profile=minimal
每次 new session(uuid)
源码:bridge.mjs:606-607(session key 带 uuid=无状态)· openclaw.json: zh_ar.model / systemPromptOverride
🔤
zh_en bot · 中→英文翻译
✓ 在线
›
主流程(与 zh_ar 同构,仅目标语不同)
Chuck 发中文
→
bridge 转发(无状态)
→
gpt-5.1 systemPrompt 翻英
→
英文原文返回
异常路径
❌ 同 zh_ar(OpenAI 不通)
处置一致。
OpenAI gpt-5.1
systemPromptOverride
无状态 session
📓
memo bot · 备忘录提炼助手(Chuck 自用 8 类模板归档)
✓ 在线
›
主流程
Chuck 发备忘/决策
→
bridge 转发session key 不带 uuid(稳定)
→
memo agent 读自己 workspace~/MINISO_Agents/agents/memo/
→
按 8 类模板归档
→
回确认 + 归档路径
异常路径
❌ Anthropic API 不通
CardKit 卡住报错。Chuck 重发即可。
⚠️ session 文件损坏
openclaw 启动时会容忍,但会丢之前对话记忆。
手动删
~/.openclaw/agents/memo/sessions/*(Chuck 要接受丢对话)。
Anthropic opus-4-6
~/MINISO_Agents/agents/memo
自己 workspace 独立
有状态
源码:bridge.mjs:53-64(workspace + STATELESS_AGENTS 清单,memo 不在其中)
📋
task bot · 任务催办助手
✓ 在线
›
主流程
Chuck 发催办/新任务
→
bridge 转发(无状态)
→
task agent 读 tasks.jsonl
→
增/改/查任务
→
回任务清单
异常路径
❌ tasks.jsonl 损坏
JSON 按行读取,单行坏只跳那行。但如果全坏,所有报表/逾期检查都挂。
最近一次 weekly_backup 里有副本。
Anthropic opus-4-6
tasks.jsonl
被 cron 高频复用
✍️
polish bot · 文字润色助手(中+阿双语输出)
✓ 在线
›
主流程(独特:双语分卡推送)
Chuck 发草稿
→
bridge 转发
→
polish agent (gpt-5.1)润色中文 + 译阿
→
输出含分割符--- [FORWARD-AR] ---
→
bridge 正则切两段FORWARD_AR_RE
→
先推中文卡,再推阿文卡
异常路径
❌ polish 忘记输出分割符
bridge 直接推原文 1 条,Chuck 看到中文和阿文混在一起。
polish prompt 强调规则;偶发不是 bug。
❌ OpenAI 不通
同 zh_ar/zh_en,回错误卡。
OpenAI gpt-5.1
systemPromptOverride 含 forward 规则
FORWARD_AR_RE 切分
源码:bridge.mjs(定义 FORWARD_AR_RE 并在 polish 回复后切段推送)
三、定时触发(Cron 10 项)
⏰
daily_scan · 每日飞书聊天扫描 + 任务/事件双提取
✓ 已修复(增量)
›
主流程
gateway cron 触发
→
isolated session独立 context 启 task agent
→
task agent 调 Bashnode feishu-scan.mjs --days 1 --extract-tasks --extract-events --deliver-chuck
→
loadArchiveState()读 messages.jsonl 建 seenIds + chat_id 水位线
→
只拉 > 水位线的新消息增量,不重复扫
→
main agent 提任务/事件
→
append 到 tasks/events.jsonl
→
send_to_chuck 推摘要
异常路径
❌ feishu-user-token.json refresh 失败
脚本 exit non-zero;task agent 看到 shell 错误。
健康检查 health_check 会推飞书警告;Chuck 点重新授权链接。
❌ 超过 600s timeout
gateway kill task session。部分消息可能已写 tasks.jsonl 但未推 Chuck。
下一次 cron 靠水位线接着继续(增量机制保证不重复)。
⚠️ 只跑周日-周四(0-4)
cron
0 7 * * 0-4 意思是周五周六不跑(埃及周末)。这是设计行为。
Feishu user_token
Anthropic opus-4-6
messages.jsonl (watermark)
tasks.jsonl / events.jsonl
send_to_chuck.mjs
源码:feishu-scan.mjs:64-84(loadArchiveState / watermark)· cron/jobs.json job=60b7556b...
⏰
health_check · 每日系统健康自检
✓ 在线
›
主流程(6 项并检)
07:05 cron 触发
→
task agent 调 Bashnode ~/MINISO_Agents/scripts/health_check.mjs
→
6 项依次检查launchd / gateway:18789 / cron / 磁盘 / bridge.err / feishu token
→
issues.length > 0 ?
→
推飞书 / 静默
异常路径(每一项的作用)
❌ launchd 服务缺失
说明 ai.openclaw.gateway 或 com.openclaw.feishu-bridge 挂了。推飞书"服务异常"。
通常 launchd 自动拉起;如果反复失败要看 plist 配置。
❌ gateway :18789 TCP 不通
gateway 启了但端口没起来。
launchctl kickstart -k gui/$(id -u)/ai.openclaw.gateway❌ 某 cron consecutiveErrors ≥ 2
说明某个定时任务连续失败 2 次+。这是给 Chuck 的早期预警。
根因查 session 历史:
openclaw sessions list --agent task --limit 5。❌ 磁盘 < 10GB
数据目录可能写不下去。
最可能是 session .jsonl 或 .bak 文件堆积,手动清。
❌ bridge.err 最近 1h 有 FATAL
bridge 崩过。
看
~/.clawdbot/logs/feishu-bridge.err.log。❌ Feishu API token 无效
tenant_access_token 过期或 APP_SECRET 丢。
重新授权或修 secrets。
launchctl
/dev/tcp 探活
Feishu tenant token API
send_to_chuck.mjs
源码:health_check.mjs:1-174(6 项并串联检查)
⏰
daily_report · 每日日报
✓ 在线
›
主流程(3 条独立消息发 Chuck)
07:30 cron 触发
→
task agent 调 Bashnode generate_report.mjs --mode daily --deliver-chuck
→
读 events.jsonl + tasks.jsonl按 Cairo 日窗口过滤昨日
→
callMainAgent (via openclaw CLI execFileSync)注意:用 subprocess 不走 gateway
→
main agent 按模板出日报SECTION_WHITELIST 过滤
→
formatCostSection 聚合扫 session.jsonl 的 message.usage.cost.total
→
3 条消息:日报 + todo + 成本
异常路径
❌ callMainAgent subprocess 超时(420s)
有 3 次重试(每次间隔 60s)。重试完全败就跳过,但不阻塞 cron。
generate_report.mjs:callMainAgentWithRetry 保护。
❌ events.jsonl 当天空
报告仍会生成但内容稀薄。main agent 在 prompt 里会说"昨日无事件"。
❌ 发飞书失败
报告已生成但推送失败。Chuck 看不到日报。
下次 health_check 不会发现(health 只看服务,不看报告送达)。这是监控盲区。
Anthropic opus-4-6 (main)
events.jsonl / tasks.jsonl
openclaw CLI subprocess
api_cost.mjs 聚合
send_to_chuck.mjs x3
源码:generate_report.mjs:callMainAgent(execFileSync 420s timeout)· api_cost.mjs:computeCost
⏰
weekly_report · 每周日周报 【当前故障】
✗ lastStatus=error
›
主流程(与 daily 同构,仅窗口改 7 天)
周日 08:00 触发
→
generate_report --mode weekly
→
过滤近 7 天
→
main agent 周报模板
→
3 条消息
异常路径
❌ 当前触发的异常:LLM network error
可能是:Anthropic 429/502、openclaw gateway 到 Anthropic 的 HTTPS 链路断、token 级错误。
等下次 cron 自然重试(下一个周日);或 Chuck 手工触发
openclaw cron run weekly-report-...。
同 daily_report
Anthropic 网络敏感
⏰
monthly_report · 月报
✓ 在线
›
主流程(独特:双轮 review)
1号 08:00 触发
→
generate_report --mode monthly
→
过滤上日历月
→
main agent 一轮草稿
→
main agent 二轮 review比 daily/weekly 多这一步
→
3 条消息
异常路径
❌ 双轮意味着 2× LLM 调用
API 成本月末翻倍。且第二轮若失败会直接用第一轮(有 fallback)。
同 daily_report
双轮 review 逻辑
⏰
overdue_check · 逾期任务扫描
✓ 在线
›
主流程
17:00 触发
→
task agent 扫 tasks.jsonl本次没脚本,纯 agent 原生 bash 筛
→
筛 due_date < 今天 & status ∈ 待启动/进行中/疑似
→
生成表格
→
echo | send_to_chuck.mjs -无逾期则不发
异常路径
❌ agent 把条件 "status ∈ {待启动, 进行中, 疑似任务待确认}" 理解错
可能漏报或多报。Chuck 看到的是结果表格,不容易察觉。
没有脚本级测试。建议未来抽一个 check_overdue.mjs 把逻辑固化成代码。
task agent 纯 prompt 实现
tasks.jsonl
send_to_chuck.mjs
⏰
distill_main · 每晚 main 记忆蒸馏 【唯一 agent=main 的 cron】
✓ 在线
›
主流程(唯一 agent=main 原因:需要访问 main 自己的 MEMORY.md)
23:30 触发
→
main agent Read MEMORY.md共享 memory index
→
Read memory/YYYY-MM-DD.md今日 Chuck 对话日志
→
对比分析哪些规则/偏好值得入长期
→
Write 新 .md(按 frontmatter 格式)
→
更新 MEMORY.md 索引行
异常路径
❌ 蒸馏写错 memory
main 可能错把临时对话内容当成长期规则入库。对 Chuck 是"我没说过也没同意过的偏好被记了"。
后续对话中 Chuck 纠错→蒸馏会自我更正。另外 memory/ 每次都有 git(实际上没有专用 git,但 weekly_backup 会覆盖保存)。
❌ 撞上当日 api 成本上限 / 限流
main 的 Anthropic 账户当天已刷满(不太可能,Chuck 月费 ~$17),蒸馏失败。
下一天自然重试;丢一天蒸馏是可接受的。
Anthropic opus-4-6
~/.openclaw/workspace/memory/*.md
~/.claude/projects/-Users-liukeyi/memory/
主要的自进化机制
⏰
session_cleanup · 清工具 bot 过期 session
✓ 在线
›
主流程
1 号 03:00 触发
→
task agent 调 Bashnode cleanup_stateless_sessions.mjs
→
遍历 STATELESS_AGENTS[zh_en, zh_ar, polish, memo, task]
→
保留 main session + 30天内 session
→
unlink 旧 .jsonl + 改 sessions.json原 sessions.json 写 .bak.
→
回 [done] removed=N kept=M freed=XKB
异常路径
❌ sessions.json JSON 损坏
脚本 JSON.parse 会抛。某个 agent 跳过,不影响其他。
❌ unlink 权限不足
打印 warn,继续跑其他文件。
~/.openclaw/agents/*/sessions/
30 天保留期
.bak 策略
⏰
skill_zh_sync · skill 中文触发词自动补全
✓ 在线
›
主流程
周一 07:15 触发
→
task agent 调 Bashnode ensure_skill_zh.mjs
→
扫 workspace/skills/*/SKILL.md
→
对每个纯英文 descexecFileSync openclaw agent --agent main
→
main 出中文前缀
→
原文件 .bak,改 description
→
send_to_chuck 推摘要
异常路径
❌ main subprocess 失败(180s 超时)
当前 skill 跳过,记入 failed 列表;其他继续。
❌ main 回的文本不是 " / " 结尾
脚本自动补。容忍度高。
⚠️ 该跑一次就不该再跑(除非加新 skill)
目前所有 skill 都已补过中文触发词。周度跑一次是防御性的(防 skill 更新或新增),绝大多数周回"已有中文,全跳过"。
~/.openclaw/workspace/skills/*/SKILL.md
main subprocess 180s/次
send_to_chuck 仅有变更时推
⏰
weekly_backup · 每周配置备份到飞书(自恢复版)
✓ 在线
›
主流程
周一 06:00 触发
→
task agent 调 Bashnode backup_to_feishu.mjs
→
stage 目录 + 模板化plist/cron 里绝对路径 → __HOME__/__NODE_BIN__
→
写 RESTORE.md + restore.sh + MANIFEST.json
→
tar.gz 打包含 .openclaw / .clawdbot / MINISO_Agents / .claude/memory / LaunchAgents
→
Feishu 文件上传 API
→
im.v1.message.create file 类型
→
发 Chuck(文本 + 文件两条)
异常路径
❌ tar 打包失败 / 超过飞书 30MB 限制
脚本 process.exit(1)。本次备份失败,但不影响下一次。
EXCLUDES 已排除 node_modules / sessions / logs。当前预期 < 30MB。
❌ Feishu 上传 API 失败
tar.gz 已在本地
~/MINISO_Agents/backups/,保留最近 4 次。手动复制到 iCloud 或下次 cron 重发。
⚠️ secrets 在归档里
飞书文件可视作"Chuck 个人云盘"。敏感信息走的是飞书私聊渠道,Chuck 接受这个风险。
Feishu file upload API
tar + gzip
20+ 模板化路径
核心灾难恢复
含 secrets(Chuck 已知)
源码:backup_to_feishu.mjs:111-228(RESTORE.md 生成)· 234-414(restore.sh 生成)
四、审计结论(Chuck 请核对)
📋 Chuck 审阅清单
›场景清单是否齐全?
- 6 个飞书 bot(已上线,每个一张卡)
- 10 个 cron(全部按时间从早到晚列出)
- 是否还有其他你会用但上面没画的场景?比如:手动敲 openclaw CLI、自己跑某个脚本、peekaboo/GUI 自动化——这些都未上线 cron,未包括。
依赖/外部服务
- Anthropic API(main / memo / task)
- OpenAI API(zh_ar / zh_en / polish + Whisper STT)
- Feishu OpenAPI(消息 / 文件 / user token)
- Mac launchd(2 个常驻服务)
- 本地磁盘(≥10GB 空闲)
- 本地文件状态(tasks.jsonl / events.jsonl / messages.jsonl / people / stores / chuck_open_id / chuck_union_id / feishu-user-token)
当前问题列表
- 🔴 weekly_report lastStatus=error(LLM network error)——下周日会自动重试,如果那时也失败再查根因。
- 🟡 监控盲区:health_check 只看服务状态,不看"报告有没有到 Chuck 手里"——如果 Feishu 送达失败 Chuck 不会被提醒。
- 🟡 overdue_check 无专用 script,靠 task agent 纯 prompt 跑,不稳定。
记忆将被修正(审计中发现的 memory 漂移)
project_ai_matrix.md1.1 节 "命令前缀路由" 描述错误 → 改为 "1 bot = 1 app = 1 agent"project_ai_matrix.mddaily_report agentId 表述 → 澄清"入口 agent=task,内容由 task 调 main 生成"project_ai_matrix.mdskill_zh_sync 频率"每日" → 改为"每周一"
这张页面怎么用
- 上方标签页 "用户触发 / 定时触发 / 异常项" 可快速筛选
- 点击任何卡片标题展开详情(主流程 + 异常路径 + 依赖 + 源码位置)
- 本页面路径:
/tmp/miniso_flow_audit/index.html(自包含单文件,离线可开,不依赖任何 CDN) - 如果要长期挂到
miniso-ai-matrix.pages.dev风格域名跟 Chuck 说"部署",我发一个新子域名或挂到现有 Cloudflare Pages 项目