Git 仓库初始化本质

OpenClaw 在 workspace 目录下执行 git init，本质是给整套数字公司资产（SOUL.md、AGENTS、技能配置、流程脚本等）建立本地版本库，只有初始化完成后，自动备份、提交推送、版本回滚功能才能生效。

初始化不会自动执行，必须满足指定触发条件才会运行。

二、四大初始化触发时机（按执行先后）

1. 手动主动初始化（最常用、推荐）

在 OpenClaw 后台「资产备份 / Git 同步」配置面板完成 Gitee 仓库地址、鉴权信息（SSH 密钥 / 私人令牌）填写后，点击初始化仓库按钮，引擎立刻执行：

1. 进入 workspace 根目录执行 git init；
2. 自动生成适配 OpenClaw 的 .gitignore，过滤缓存、运行日志、本地数据库、临时缓存文件；
3. 绑定远程仓库 git remote add origin 你的Gitee仓库地址；
4. 首次全量提交所有 workspace 内业务配置资产。 适用场景：首次配置 Gitee 自动备份、更换新远程仓库。

2. 自动检测无本地 Git 库，保存备份配置时自动初始化

操作流程：

1. 填写完整 Gitee 仓库信息、开启实时备份、设置同步规则；
2. 直接点击「保存配置」，不手动点初始化按钮；
3. OpenClaw 内核扫描 workspace，检测目录不存在 .git 隐藏文件夹；
4. 后台静默自动执行 git init、绑定远程、生成忽略文件，无需人工干预。 触发前提：备份插件已启用、远程仓库参数填写完整、本地无 Git 版本库。

3. 首次触发自动备份（文件变更 / 定时兜底同步）延时初始化

场景：配置完备份但未保存、未手动初始化，直接修改 workspace 内 SOUL.md/AGENTS.md 等配置文件：

1. 文件监控捕获文件改动，触发自动备份流程；
2. 前置校验发现 workspace 无本地 Git 仓库；
3. 自动执行初始化流程，完成后再执行 add/commit/push 推送至 Gitee。 特点：存在少量延时，第一次修改会多一步初始化耗时，后续变更直接同步。

4. 多设备拉取远程仓库时初始化（全新空白设备）

新设备部署 OpenClaw，空白 workspace，填写同一 Gitee 仓库地址，执行「拉取远程资产」：

1. 引擎先在空白 workspace 执行 git init；
2. 绑定远程源，执行 git pull 拉取远端全部数字人组织配置；
3. 完成多设备资产同步，本地自动生成 Git 版本库。

三、不会触发初始化的几种情况

1. workspace 中已存在 .git 文件夹（曾经初始化过），无论重新保存配置、修改文件，都不会重复执行 git init；
2. 仅打开备份配置页面，未填写完整 Gitee 仓库地址、未开启同步开关；
3. 仅临时启用备份插件，但未填写远程仓库信息；
4. 仅修改临时缓存文件、被 .gitignore 过滤的日志 / 数据库文件，不会触发备份流程，自然不会初始化 Git。

四、补充关键细节

1. 初始化仅作用于 workspace 工作目录，OpenClaw 程序本体安装目录不会纳入 Git 管理；
2. 初始化只会执行一次，后续更换 Gitee 仓库地址时，引擎仅更新 remote 远程地址，不再重复 init；
3. 若初始化失败（权限不足、目录只读），备份日志会打印报错，自动同步功能暂停，需手动重新执行初始化按钮。