OpenClaw：GitHub 配置同步、按日版本与参数影响分析

能力总览（与用户任务一一对应）

| # | 能力 | 实现要点 |

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

| 1 | 配置在 GitHub | 用 Raw URL、Contents API 或已克隆仓库读取；私有库需 token。 |

| 2 | 从链接得「项目名」并找配置 | 解析 owner/repo；项目文件夹名默认 = repo；在仓库内搜索 配置文件/、config/ 等及 字段说明.md。 |

| 3 | 在工作区建项目目录 | {workspace}/{repo}/，其下为按日期的版本子目录（见下节）。 |

| 4 | 读配置与字段说明 | 成对加载；YAML 展平为点分键与表格「字段」列对齐。 |

| 5 | 下载到工作区 | 每次非最新或首次同步时，写入新版本目录内，保持与仓库相同的相对路径。 |

| 6 | 用户提问 → 解释参数与变更影响 | 必须先完成新鲜度检查；再基于当前最新版本目录作答（见「参数解释答题模板」）。 |

| — | 版本管理 | 每次成功同步用更新当日日期作为文件夹名；历史目录保留不覆盖。 |

| — | 每次提问先判断是否最新 | 比较远程 remote_ref 的 tip commit_sha 与 .openclaw-config-state.json；一致则只读 latest_version_dir；不一致则先同步再分析。 |

何时使用

• 用户提供 GitHub 仓库链接（或 owner/repo），需要定位、同步、解释配置。
• 用户问「这个参数什么意思」「改了这个会怎样」「dev 和 prod 差在哪」等——默认必须先校验本地是否仍对应远程最新提交。

核心约定

• 配置文件与说明常成对出现，例如 g3fo-user-dev.yml 与 g3fo-user-dev-字段说明.md。
• 字段说明里 点分路径（如 app.cache.caffeine.max-size）对应 YAML 嵌套结构；分析前将 YAML 展平再与表格对齐。

一、目录布局与元数据

1. 路径约定

• 工作区根：OpenClaw/Cursor 当前 workspace 根，或用户指定的绝对路径。
• 项目根：{workspace}/{repo}/（repo 为仓库 slug，除非用户另指定文件夹名）。
• 版本目录：{workspace}/{repo}/{版本文件夹名}/...，其下子路径与 GitHub 仓库内相对路径一致，例如：
• .../2026-04-08/配置文件/g3fo-dx-dev.yml
• .../2026-04-08/配置文件/g3fo-dx-dev-字段说明.md

2. 版本文件夹命名

• 每次拉取远程并成功写入时新建目录（不覆盖旧目录）。
• 默认名：同步当日日期 YYYY-MM-DD（在回复中说明所用时区，如 UTC+8）。
• 同一天多次同步：若该目录已存在，使用 YYYY-MM-DD_2、YYYY-MM-DD_3 或 YYYY-MM-DDTHHmm（任选一种，与 state 一致）。

3. 元数据文件（必须）

路径：{workspace}/{repo}/.openclaw-config-state.json

用于记录「当前应读哪一版」以及「上次同步时远程 ref 指到哪一提交」。所有「当前配置」类读取只认 latest_version_dir 指向的目录。

建议字段：

| 字段 | 含义 |

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

| owner, repo | GitHub 坐标 |

| remote_ref | 跟踪的分支名或 tag（如 main、v1.2.0） |

| commit_sha | 同步时该 ref 在远程的 tip 完整 SHA |

| latest_version_dir | 当前应使用的版本目录名（如 2026-04-08） |

| synced_at | ISO 时间戳（可选） |

| tracked_paths | 已同步的配置与说明文件在仓库中的相对路径（可选） |

示例：

{
  "owner": "acme",
  "repo": "g3fo-config",
  "remote_ref": "main",
  "commit_sha": "a1b2c3d4e5f6789abcdef0123456789abcdef01",
  "latest_version_dir": "2026-04-08",
  "synced_at": "2026-04-08T10:30:00+08:00",
  "tracked_paths": [
    "配置文件/g3fo-dx-dev.yml",
    "配置文件/g3fo-dx-dev-字段说明.md"
  ]
}

二、每次用户提问时的强制顺序：先判断是否最新

在回答任何依赖「仓库里当前配置内容」的问题之前（解释参数、影响、环境对比等），先执行本节。未完成判断前，不要仅凭旧本地文件下结论。

步骤 A：确定跟踪目标

• 从用户链接或对话中确定 owner、repo、remote_ref（无则默认 main 或仓库默认分支，见 API）。
• 若不存在 .openclaw-config-state.json：视为非最新，进入「全量同步」后再分析。

步骤 B：查询远程 tip SHA

• 使用 GitHub API 获取 remote_ref 当前指向的 commit SHA（分支 tip 或 tag 解析对象）。
• 与 state.commit_sha 比较（remote_ref 须一致；若用户改跟踪分支/tag，一律重新同步并更新 remote_ref）。
• 默认策略：以 ref 的 tip commit 为准；任一新推送都会触发重新拉取，避免遗漏同分支上其它提交带来的配置变更。
• 可选：仅当 tracked_paths 下文件变更才更新（需按路径查 last commit，更省带宽但实现更复杂）。

步骤 C：判定与动作

| 条件 | 动作 |

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

| SHA 一致 且 latest_version_dir 存在 | 仅 Read 该目录下文件，再进行分析或解释。 |

| SHA 不一致 或 无 state | 新建版本目录 → 发现并下载配置与 字段说明.md → 更新 state → 简短告知用户（版本目录名、短 SHA）→ 再分析。 |

步骤 D：远程不可用时的降级

若 API 失败（网络、权限、限流）：

• 不得静默假装最新；应说明失败原因。
• 可在用户同意下，使用 state.latest_version_dir 对应目录中的上次成功快照，并明确标注「未校验远程，可能已过期」。
• 若用户指定只分析某历史日期目录，可跳过 B，但须声明依据的是哪一版本地快照。

三、全量同步子流程（首次或过期时）

在「步骤 C」要求同步时执行：

1. 按「版本文件夹命名」规则新建目录（不覆盖已有日期目录）。
2. 发现文件：在仓库内搜索 配置文件/、config/ 等及 .yml/.yaml/.properties 与成对的 字段说明.md（见 reference.md）。
3. 下载：Raw 或 Contents API 拉取正文，写入新版本目录内，相对路径与仓库一致。
4. 写入/更新 .openclaw-config-state.json：commit_sha、latest_version_dir、remote_ref、tracked_paths、synced_at。
5. 私有仓库：确保环境具备 GITHUB_TOKEN 或等价方式（见 reference）。

四、在通过新鲜度检查之后：分析工作流

1. 定位仓库与配置路径（若同步时尚未完成）

解析 URL；若只给根链接，按典型目录与扩展名搜索；记录 remote_ref 与默认分支。

2. 获取内容

优先 Raw URL；目录列举用 API；本地已有克隆则可直接 Read。

3. 解析配置与字段说明

• 每个配置文件匹配同目录或同前缀的字段说明。
• YAML 展平；properties 键直接对齐。
• 从 Markdown 表格提取字段路径、类型、说明。

4. 回答「改了什么、会怎样」

有两次状态（两文件、两 commit、或片段）：

• 做点分键 diff；逐键查字段说明；无说明的键单独列出。
• 使用下方「变更摘要」模板。

仅描述意图（如「把 Redis 库从 2 改成 5」）：

• 映射到键；引用说明；区分文档确定项与推断项。

变更摘要（输出模板）

## 变更摘要
- 共 N 个键变化（M 个有文档依据）

| 配置键 | 原值 | 新值 | 文档摘要 | 可能影响 | 风险 |
|--------|------|------|----------|----------|------|
| ... | ... | ... | ... | ... | 低/中/高 |

## 文档未覆盖的键
- ...

## 建议验证
- 重启/热更新是否生效
- 依赖服务（DB/Redis/注册中心）是否一致

参数解释答题模板（单个或若干键）

## 参数说明（基于当前最新版本目录：{latest_version_dir}，commit 短 SHA：{short_sha}）

| 配置键 | 当前值 | 含义（文档） | 若修改的典型影响 | 风险 |
|--------|--------|--------------|------------------|------|
| ... | ... | ... | ... | 低/中/高 |

• 若某键无文档：标注「文档未覆盖」，推断须标明为推断。

风险分级参考

• 高：鉴权、密钥、生产 URL、关闭安全策略、数据隔离。
• 中：端口/注册发现、限流重试、缓存、连接池。
• 低：日志级别、非关键超时、仅本地开发开关。

注意事项

• 禁止在对话或日志中输出完整密钥、密码、Token；可用掩码。
• 私有仓库需 read 权限；无权限时引导用户配置 token 或提供可访问路径。
• 不同环境文件之间值不同未必是错误，先确认对比的是否为同一环境/同一文件。

附加资源

• URL、API、点分键、一致性判断细节见 reference.md。