OpenClaw Git 管理器

OpenClaw 配置文件的版本控制 — 支持带差异比对的提交、历史版本对比、回滚至任意先前版本。

核心定位

任何未通过 Git 记录的配置变更，都是一次潜在的数据丢失事件。 本技能将 OpenClaw 配置管理从“希望一切不出问题”转变为“我总能回退”。

所追踪的内容：

• ~/.openclaw/openclaw.json — 主配置文件
• ~/.openclaw/credentials/*.json — 凭据配置文件
• ~/.openclaw/agents/ — Agent 定义
• ~/.openclaw/flows/ — Flow 定义
• ~/.openclaw/skills/ — 自定义技能配置

不追踪的内容： memory/、logs/、media/、tmp/、trash/、canvas/、npm/、completions/、service-env/、tasks/、.DS_Store。

仓库初始化

首次使用时，若 ~/.openclaw/ 下尚无 Git 仓库，该技能将自动初始化一个 Git 仓库，并配置合理的 .gitignore 文件，以排除运行时数据。

命令模式

/openclaw-git-manager commit

暂存并提交当前配置状态，并附上可读性良好的提交信息。

适用于以下场景：

• 配置刚被修改（通过向导、手动编辑或其它技能）
• 在对 openclaw.json 做高风险变更前
• 成功执行 doctor 或 config 后且状态发生变更

执行步骤：

1. 检查自上次提交以来有哪些受追踪文件发生了变更（git status）
2. 对每个变更文件，展示简洁的差异摘要（仅显示变更的键名，而非完整内容）
3. 提示用户确认或编辑提交信息
4. 暂存所有已变更的受追踪文件
5. 使用该信息完成提交，消息前缀为 config:
6. 报告提交哈希值及变更文件数量

禁止操作：

• 提交原始密钥或真实 API 密钥（若 credentials/ 中含真实密钥则发出警告）
• 提交二进制文件或缓存文件
• 在未说明变更内容的情况下提交

/openclaw-git-manager log

展示提交历史，包含单行摘要与差异概览。

适用于以下场景：

• 用户希望了解“什么内容何时发生了变更”
• 诊断配置回归问题（这个问题是何时引入的？）
• 查找一个已知可用的版本用于恢复

执行步骤：

1. 运行 git log --oneline -20 展示最近 20 条提交
2. 对每条提交，展示：简短哈希值、相对时间、消息首行
3. 若用户请求查看某特定提交详情，则展示完整差异：git show --stat（变更文件列表） + git show （补丁内容）
4. 按时间倒序（最新在前）展示提交，并为每条提交编号以便引用

禁止操作：

• 对大文件展示完整文件内容
• 在差异输出中包含已被忽略路径（如 memory/、logs/ 等）

/openclaw-git-manager diff

精确展示两次提交之间，或工作树与 HEAD 之间的差异。

适用于以下场景：

• 比较当前未提交状态与上一次提交
• 比较两个历史提交
• 验证回滚操作将带来的具体变更

执行步骤：

1. 若无参数：展示所有未暂存变更与 HEAD 的差异
2. 若指定 --from --to ：展示两个提交之间的差异
3. 差异格式需包含文件头，并按文件统计 +/- 行数
4. 对于 JSON 文件，可选地以结构化方式呈现 key: value 变更
5. 汇总统计：N 个文件变更、N 行插入、N 行删除

禁止操作：

• 展示二进制差异（统一表述为“文件已变更，N 字节”）
• 展示已被忽略路径（如 memory/、logs/ 等）

/openclaw-git-manager restore

回滚至某历史提交，或恢复特定文件。

适用于以下场景：

• 某次配置变更引发问题，用户希望回退
• 用户通过 log 找到一个稳定可用的提交，并希望恢复至该版本
• 用户说“撤销这次变更”或“回到之前的状态”

执行步骤：

1. 若用户指定了提交（哈希值或 log 中的编号）：将整个工作树恢复至该提交
2. 若用户指定了某个具体文件：仅将该文件恢复至该提交对应版本
3. 先展示预览差异：当前状态将发生哪些变更
4. 覆盖当前文件前，必须获得用户显式确认
5. 恢复完成后，自动创建一条恢复标记提交：config: restore to ()
6. 报告哪些文件被修改，以及新的 HEAD 提交

恢复模式：

• 全树恢复：git checkout -- .（所有受追踪文件）
• 单文件恢复：git checkout -- path/to/file
• 硬重置（破坏性）：git reset --hard —— 仅当用户明确说出“hard reset”时才执行

禁止操作：

• 未经用户显式确认，执行破坏性恢复（如 hard reset、强制 checkout）
• 恢复至非当前 HEAD 的祖先提交（避免 detached HEAD 风险）

/openclaw-git-manager status

展示当前工作树状态。

适用于以下场景：

• 用户询问“当前配置状态如何？”
• 提交前，确认哪些文件将被纳入提交
• 恢复后，验证工作树是否已清理干净

执行步骤：

1. 运行 git status --short 获取简洁视图
2. 展示：与远程分支相比领先/落后多少提交（如有）、当前所在分支
3. 列出所有未提交变更的文件名
4. 报告工作树是否“干净”，或“N 个文件已变更”

禁止操作：

• 在 status 模式下展示完整差异（请使用 diff 命令）

执行入口

主入口始终为 scripts/git_manager.py，从 ~/.openclaw/ 目录调用。

# 在 ~/.openclaw/ 目录下执行
python3 ~/.openclaw/workspace/skills/openclaw-git-manager/scripts/git_manager.py  [args]

# 支持命令：commit、log、diff、restore、status

脚本根据已安装技能目录解析自身位置，而非当前工作目录。

配置文件路径

Gitignore 规则（内嵌）

以下路径均被排除在追踪范围之外：

# 运行时数据（排除）
memory/
logs/
media/
tmp/
trash/
canvas/
npm/
completions/
service-env/
tasks/
.DS_Store

# Node.js / npm
node_modules/
package-lock.json

# 编辑器
*.swp
*.swo
.vscode/
.idea/

# OpenClaw 内部文件（非用户配置）
cron/
devices/
exec-approvals.json
update-check.json
skills-trigger-index.json
subagents/
delivery-queue/

禁止行为

• 提交真实 API 密钥、Bearer Token 或密码 — 必须先行脱敏
• 使用 git push — 本仓库仅为本地记录，不作为共享仓库
• 合并分支 — 保持线性历史以降低恢复复杂度
• 直接修改 .git/ 目录 — 始终通过标准 Git 命令操作
• 追踪 memory/ 或 logs/ — 这些属于运行时数据，而非配置

质量标准

一条优秀的提交信息应能让未来的阅读者快速回答：

• 什么发生了变更？（具体某个配置项、文件或一组设置）
• 为何变更？（变更意图 — 如“启用 TTS”，而非“更新了 JSON”）
• 此前状态如何？（可通过差异直观看到）

示例提交信息：

• ✅ config: enable minimax TTS in production profile
• ✅ config: add claude-sonnet model to local provider list
• ✅ config: rollback agent definitions to pre-migration state
• ❌ config: update
• ❌ config changes
• ❌ stuff

优质 vs 劣质提交信息

日志格式

commit a1b2c3d  2 小时前   config: enable minimax TTS
commit b2c3d4e  昨天      config: add claude-sonnet to providers
commit c3d4e5f  3 天前     config: initial checkpoint

回滚输出契约（强制要求）

每次执行 restore 命令后，输出必须包含以下四项：

1. Files restored — 已恢复的文件列表
2. New HEAD — 当前工作树指向的新提交哈希值
3. Previous state — 上一提交哈希值（供后续撤销使用）
4. Next action — 用户下一步建议操作（例如：“重启 gateway”）

技能适用性

本技能解决一个明确问题：配置变更缺乏可见性与可逆性。

它不替代备份方案、云同步或团队协作工作流。