Clawdbot Skill Update

概述

Clawdbot Update Skill 是一套专为多代理 AI 助手框架 Clawdbot 设计的更新运维工具集。核心功能围绕「备份-更新-验证-回滚」四阶段闭环展开，通过动态读取 ~/.clawdbot/clawdbot.json 自动识别所有代理工作区，无需手动维护路径列表。

核心用法

预览模式（零风险）

backup-clawdbot-dryrun.sh

输出待备份文件清单、预估容量及磁盘空间检查，不产生任何文件变更。

全量备份

backup-clawdbot-full.sh

打包配置、会话状态、凭据、定时任务、沙箱状态及所有工作区，输出至 ~/.clawdbot-backups/pre-update-YYYYMMDD-HHMMSS/。

版本更新
跟随 UPDATE_CHECKLIST.md 执行：停止网关 → 拉取代码 → 适配破坏性变更（如 v2026.1.8 的 DM Lockdown 与沙箱作用域调整）→ 运行 doctor → 测试 → 守护进程启动。

紧急回滚

restore-clawdbot.sh <backup-dir>

支持完整配置、状态及工作区恢复，也可仅回退 git 版本。

显著优点

1. 动态工作区检测：告别硬编码路径，自动适应代理增减
2. 多代理原生支持：每个代理独立打包 workspace-<agent>.tar.gz
3. 安全优先设计：dry run → 备份 → 验证的三重保险机制
4. 版本化清单：附带 BACKUP_INFO.txt 与 git commit SHA，便于溯源

潜在局限

• 依赖 jq：要求系统预装 jq 以解析 JSON 配置
• 单节点备份：备份文件默认存储于本地 ~/.clawdbot-backups/，未内置远程同步逻辑
• 破坏性变更需手动适配：如 v2026.1.8 的策略切换需用户执行 jq 命令修改配置，非全自动
• 网关停服窗口：更新流程需停止 gateway 服务，对高可用场景需配合负载均衡

适合人群

• 运行多代理 Clawdbot 实例的运维者
• 追求「可回滚」更新策略的谨慎型用户
• 需要维护 WhatsApp/Telegram/Discord 等多渠道接入的复杂配置场景

常规风险

| 风险点 | 缓解措施 |

|--------|----------|

| 备份期间磁盘空间不足 | dry run 预先检查 |

| 更新后配置不兼容导致网关启动失败 | `pnpm clawdbot doctor` 自动诊断 + 备份随时回滚 |

| OAuth token 过期 | 更新后执行 `pnpm clawdbot providers login` 重授权 |

| 沙箱隔离失效 | 验证 `sandbox.scope` 显式设置为 `"agent"` |

建议生产环境执行更新前，先将备份目录同步至异地存储（如 S3/rsync），避免本地磁盘故障导致备份与生产同时丢失。

核心用法

Clawdbot Update Skill 是一套面向多代理 AI 网关的运维脚本集合，提供从备份、更新到回滚的完整工作流。核心操作分四步：

1. 预检与预览：backup-clawdbot-dryrun.sh 零风险展示待备份文件、预估体积及磁盘空间，支持动态检测所有代理工作区。
2. 全量备份：backup-clawdbot-full.sh 自动打包配置文件、会话状态、多代理数据、凭据、定时任务及沙盒状态，生成带时间戳的备份目录 ~/.clawdbot-backups/。
3. 更新执行：依据 UPDATE_CHECKLIST.md 完成网关停机、代码拉取、依赖重装、配置迁移、医生检查与灰度测试。
4. 回滚恢复：restore-clawdbot.sh <backup-dir> 一键还原所有配置、状态与工作区，支持紧急场景下快速恢复。

脚本采用纯 Bash 编写，依赖系统标准工具（tar、jq、git、cp），零外部网络调用，通过 set -e 与严格路径校验保障执行安全。

显著优点

• 动态多代理感知：自动读取 ~/.clawdbot/clawdbot.json 中的工作区路径，支持任意数量代理，无需硬编码。
• 零依赖零网络：无需额外运行时或 API 密钥，纯本地文件操作，离线环境亦可使用。
• 细粒度回滚：支持完整状态还原，包括 Git 版本、配置、会话及工作区数据，回滚过程可中断可重试。
• 安全先验：Dry Run 模式让用户在真正执行前全面掌握影响范围；备份后自动生成 BACKUP_INFO.txt 供人工核验。
• 版本兼容性提示：内置 v2026.1.8 重大变更说明（DM 策略、Sandbox 作用域、UTC 时间戳），并提供 jq 命令示例协助配置迁移。

潜在局限

• T3 来源等级：作者为个人开发者 Pascal Schott，虽 GitHub 贡献记录良好，但仍属社区项目，尚未纳入组织级治理。
• 输入校验可强化：恢复脚本对 $1 参数缺乏严格的目录存在性与完整性检查，误输路径可能导致非预期行为。
• 无代码签名：当前分发缺乏 GPG 签名或 SHA256 校验和，存在供应链篡改的理论风险。
• Bash 可移植性：部分语法（如 sponge）依赖 moreutils，极简环境可能需额外安装。

适合人群

• 自托管 Clawdbot 的生产环境运维者
• 需要维护多代理（WhatsApp/Telegram/Discord/Slack 等）路由的复杂部署
• 追求“可回滚更新”策略的保守型用户
• 离线或受限网络环境下的 Clawdbot 用户

常规风险

| 风险类型 | 说明 | 缓解措施 |

|---------|------|---------|

| 配置迁移遗漏 | v2026.1.8  breaking changes 可能导致 DM 策略或 Sandbox 失效 | 严格遵循 UPDATE_CHECKLIST，使用内置 jq 示例调整配置 |

| 备份不完整 | 动态工作区检测失败或权限问题导致代理数据缺失 | 备份后人工检查 `BACKUP_INFO.txt` 与 `workspace-*.tar.gz` |

| 误操作回滚 | 恢复时指定错误目录覆盖当前状态 | 恢复前二次确认目录时间戳，必要时先手动备份当前状态 |

| 依赖缺失 | 目标系统未安装 jq/moreutils | 提前运行 `validate-setup.sh` 预检环境 |