Yixiao 的 OpenClaw
多 Agent 个人系统

为什么值得看

市面上大部分"多 agent"方案要么是云端黑盒，要么是一次性脚本。这个案例的不同之处：

• 全本地运行Mac + Homebrew + Node，没有任何云部署
• 自愈能力每日 2 次 Doctor 巡检 + 三级异常分级 + 自动修复
• 防回退设计source → deploy → runtime 三层分离，live 修复必须回灌 source
• 数据不锁定同一份真相同步到 Notion（协作）/ Obsidian（本地）/ Wiki（Git）
• 渐进式审批全局默认放行 + 精细 allowlist 例外，既安全又不打断流
• 版本化配置~/.openclaw/workspace/ 是 git repo，回溯每一次变更

系统总览

从 Telegram 单通道进入，经 Alice 路由到 17 个 agent 或 17 个 cron，全部产出通过每晚 23:47 的 Data Sync 汇总到三个终端。

Agent 设计

命名哲学：希腊女神

每个 agent 有一个希腊女神名字作为 identity，让多 agent 协作产出的日志/报告读起来像团队会议纪要，而不是匿名的 worker-01/02。

自动化骨干：17 个 Cron 任务

设计原则

三级异常分级

Doctor Evening 和 Task Health Evening 统一用以下分级处理异常：

数据流：三端同步，零锁定

每晚 23:47 Vesta 把一份产出同时同步到三个地方，再加一条事件驱动实时推送。

共享 Wiki 知识层

所有 agent 共享的知识库，独立 private git repo。三层结构：

• SCHEMA.md — 约定（页面类型、frontmatter v2、supersedes 等）
• 页面层 — concept / decision / lesson / project 四种类型
• raw-sources/ — 原始素材

三件套 CLI（wiki/bin/）

# 查询（命中直接返回页面；MISS 累计埋点，Nova 周度补页）
wiki-query.sh --q "<keyword>" --agent <name>

# 补页（非 Nova 默认写 draft，Nova 每周 promote 到正式页）
wiki-ingest.sh --type <t> --slug <s> --title "..." \
               --tags "a,b" --agent <name> \
               --body-file <f> --source-kind <k>

# 健康检查 + rebuild _index.json / index.md
wiki-lint.sh --light | --full

Owner 模式

Nova（kb agent）是唯一 wiki owner：

• 每日 07:55 light lint
• 每周日 14:00 full lint + draft promote
• 其他 agent（Alice / Luna / Athena / Thea）在各自 AGENTS.md 中已接入查询与补页流程

配置持久化：防止回退的三层设计

这是整个系统最精妙的部分。

三层分离

反灌模式 · Source Backfill

问题：CLI 改的是 runtime，但下次跑 deploy.sh 会从 source 覆盖 runtime，live 修复就丢了。

解法：任何 live 修复必须回灌 source，单独 commit。commit message 固定格式：

回退防护：同步 <日期> <触发事件> 修复到 source

分析 deploy.sh 发现 <N> 处会回退今日修复：
- config/xxx.json：<变更摘要> + 原因
- config/yyy.json5：<变更摘要> + 原因

<不属于本 repo 范畴的问题记录去向>

这个模式让配置变更有版本历史，回溯成本低。2026-04-16 和 2026-04-22 的 commit 就是两次实战应用。

profile 模板化

deploy.sh 用 config/profile.json 做模板变量替换，示例：

{
  "user_name": "Yixiao",
  "user_full_name": "Wang Yixiao",
  "github_org": "Octo-o-o-o",
  "timezone": "Asia/Shanghai",
  "openclaw_home": "~/.openclaw",
  "projects_root": "~/WorkSpace",
  "telegram_chat_id": "86xxxxxxxx"
}

agent-templates/ 下的模板用 {{USER_NAME}} / {{GITHUB_ORG}} 等占位符。部署时 sed 替换。这让整套配置可以复用给其他人 —— 改一份 profile.json 就能跑起来。

安全设计：渐进式审批

默认策略

{
  "defaults": { "security": "full", "ask": "off" }
}

全局全权放行。理由：个人本地系统，所有 agent 都是可信的，逐一审批会把节奏打碎。

精细 allowlist 例外

遇到需要特定命令高频自动执行的场景（如 node scripts/sync-notion.mjs），加到 agent 级 allowlist：

openclaw approvals allowlist add --agent ops \
  "node ~/.openclaw/workspace/scripts/sync-notion.mjs"

敏感凭证分离

secrets.json、credentials/、.env 类文件走 .gitignore，从不进 repo。通过 SecretRef 引用（如 Telegram bot token 走 file:secrets:/TELEGRAM_BOT_TOKEN）。

消息通道策略

为什么 Telegram 是主

• Bot API 稳定、支持 Markdown、机器人无封号焦虑
• 多设备同步、历史消息可搜、支持文件/图片
• 对国内网络有 gap，但个人场景用 VPN 可接受

升级流程

标准命令

npm install -g openclaw@latest
openclaw doctor          # 诊断
openclaw doctor --fix    # 或手动修复
openclaw gateway restart
bash ~/.openclaw/scripts/post-upgrade-check.sh

已知坑（2026-04-22 版）

openclaw@2026.4.20 的 npm 包有 packaging bug：grammy 和 acpx 等运行时依赖未在 package.json 声明，导致 telegram 和 acpx 插件加载失败，阻塞整个 CLI。

Workaround（记录在 Claude memory）

# 补依赖到 package.json
cd /opt/homebrew/lib/node_modules/openclaw
# 手动在 dependencies 加上：grammy, acpx, @grammyjs/runner,
#   @grammyjs/transformer-throttler, node-edge-tts, playwright-core
npm install --ignore-scripts --omit=dev --legacy-peer-deps

升级自检

post-upgrade-check.sh 自动跑：

1. 版本校验
2. 配置验证
3. binding 检查
4. frontdesk-router 加载
5. gateway 重启 + 健康检查
6. 安全审计
7. Alice 冒烟测试（4 类任务入口）

报告写到 memory/upgrade-checks/。

可复用设计模式总结

给其他人想搭类似系统的 6 条可借鉴心法：

运行足迹

除 Hero 里的 18 / 17 / 59 / 3，这里是其余跑出来的实际留痕：

关键路径

~/.openclaw/
├── workspace/              ← 配置真相源（git repo）
│   ├── config/             ← source patches
│   ├── agent-templates/    ← agent 身份四件套模板
│   ├── scripts/            ← 同步脚本 (sync-notion/obsidian/wiki)
│   ├── deploy.sh           ← 部署入口
│   └── CLAUDE.md           ← 给 AI 的项目指南
├── openclaw.json           ← 最终运行时配置
├── exec-approvals.json     ← 审批规则
├── cron/jobs.json          ← 定时任务
├── wiki/                   ← 共享知识库（独立 repo）
├── agents/<id>/agent/      ← 每 agent 的身份文件
├── workspace-<id>/         ← 每 agent 的工作区
├── scripts/                ← 运行时脚本（40+）
└── backups/                ← 备份归档