安装指南

1. ClawHub CLI 从源直接安装技能的最快方式。
   npx clawhub@latest install safe-git-push
2. 手动安装 将技能文件夹复制到以下位置之一
   全局模式
   ~/.openclaw/skills/
   工作区
   /skills/
   优先级：工作区 > 本地 > 内置
3. 提示词安装 将此提示词复制到 OpenClaw 即可自动安装。
   请帮我使用 Clawhub 安装 safe-git-push。如果尚未安装 Clawhub，请先安装（npm i -g clawhub）。
   更倾向于下载？
   获取包含原生技能文件的ZIP压缩包。
   下载技能 (.zip)

什么是

Safe Git Push 是一个 OpenClaw skill，用于将项目或选定的文件发布到 GitHub，同时避免共享工作区中的常见风险。它会检查目标目录本身是否已经是仓库，或者是否位于父仓库内部，然后在仅暂存显式选定文件之前对嵌套项目进行隔离。
该工作流程优先考虑防止泄密和杂乱内容：审查已暂存的文件列表，添加适当的忽略规则，确认分支和远程仓库，并验证上传。如果 OpenClaw 沙箱反复终止 Git push，该 skill 可以切换为通过 GitHub Contents API 单独上传文件。对于探索 Openclaw Skills 的团队，它提供了一种实用且安全第一的替代方案，以避免使用高风险的 git add . 方法。

应用场景

用户要求将项目上传、push 或备份到 GitHub。
项目嵌套在共享的 Git 工作区内，例如包含不相关项目或敏感配置的 OpenClaw 工作区。
仅应将特定文件或目录发布到远程仓库。
需要创建一个新的 GitHub 仓库，并使用项目的初始提交填充它。
Git push 在 OpenClaw 沙箱中反复超时或被终止，需要使用 Contents API 备用方案。
开发人员希望在发布前检查
.env
文件、密钥、依赖项、编辑器设置或构建输出。

工作原理

检查目标： 检查目录是否位于 Git 工作树内部，使用 git rev-parse --show-toplevel 确定仓库根目录，审查状态，并检查现有的远程仓库。
需要时进行隔离： 如果目标是父仓库的子目录，则在目标内部初始化一个单独的仓库，以便不修改父工作区。
准备安全的文件集： 添加适当的 .gitignore 条目，显式暂存仅请求的文件，并检查 git status --short 以查找密钥和不相关的内容。切勿在此工作流程中使用 git add .。
创建或选择远程仓库： 使用 gh CLI 或通过网站创建 GitHub 仓库，然后配置远程仓库并将本地分支与目标分支对齐。
提交、push 和验证： 提交已审查的文件，push 到远程仓库，并验证仓库内容，而不是将仓库创建元数据视为成功 push 的证明。
仅在反复失败后使用备用方案： 在发生至少两次与 SIGTERM 相关的 push 失败并确认远程仓库仍为空之后，使用 GitHub Contents API 单独上传文件并验证远程仓库内容。

配置指南

该 skill 是一个 agent 工作流程，而不是一个独立的包安装程序。确保 Git 和 GitHub CLI 可用，并使用获权创建或更新目标仓库的账户对 CLI 进行身份验证。

确认所需的工具和 GitHub 身份验证

git --version
gh --version
gh auth status

在暂存文件前检查目标目录

cd
git rev-parse --is-inside-work-tree
git rev-parse --show-toplevel
git status --short
git remote -v
如果目标目录位于父仓库内部且应当独立，请初始化一个嵌套仓库。仅添加预期的文件，然后在提交前审查暂存列表。

仅在目标需要自己的仓库时运行

git init -b main

添加适用于项目的忽略规则，然后暂存显式路径

git add README.md src/
git status --short
git commit -m 'Initial commit'

创建一个私有 GitHub 仓库并配置其远程仓库

gh repo create --private --description 'Project description'
git remote add origin https://github.com//.git
git push -u origin main

验证远程仓库内容

gh api repos///contents --jq 'if type == "array" then [.[].name] else .message end'
选择 main 或 master 以匹配预期的远程分支。不要使用 gh repo create --confirm；该 skill 指出此标志在当前的 GitHub CLI 版本中已被废弃。如果仓库已存在且配置了其远程仓库，请使用该远程仓库，而不是创建另一个仓库。

数据架构

该工作流程未定义自定义数据库或持久化元数据格式。它使用标准的 Git 和 GitHub 结构：
数据或文件 用途
显式暂存的项目文件 包含在提交中或上传到 GitHub 的白名单内容。
.gitignore 排除常见的杂乱内容，例如 Python 缓存、编辑器设置、临时文件以及特定于项目的构建或依赖目录。
.git/ 在初始化仓库时存储本地仓库元数据、提交、分支和远程配置。
Git 远程仓库和分支 识别目标仓库和目标分支，通常为 origin 和 main。
Contents API 请求体 JSON 在备用工作流程中，每个文件的请求体包含提交信息、分支以及在需要时编码为 Base64 的文件内容。将生成的请求体文件视为临时请求数据，而不是项目输出。
在发布之前，检查暂存文件列表中是否有 .env、私钥、包含密钥的文件名、node_modules/、虚拟环境和构建目录。仓库可见性在创建期间选择（例如使用 --private），并应根据用户的意图进行确认。

高级特性

父仓库检测：
将目标目录与 Git 报告的仓库根目录进行比较，以确定嵌套项目何时需要隔离。
显式暂存安全性：
使用命名路径和暂存文件审查，以减少凭据、无关项目或大型依赖目录的意外发布。
沙箱感知恢复：
仅在发生至少两次与 SIGTERM 相关的 push 失败后才推荐 Contents API，并在更改上传方法之前检查远程仓库是否仍然为空。
单文件 API 上传：
gh api -X PUT
，并将 PNG、DOCX 和 PDF 文件等二进制资源进行 Base64 编码，以进行单独上传。
远程验证：
通过 API 或网站检查实际的仓库内容；它警告
pushedAt
可能会反映仓库的创建而不是成功的 push。
作用域感知行为：
当用户显式希望将目录添加到当前仓库或已指定配置好的远程仓库时，避免创建嵌套仓库。

name: safe-git-push description: 从 agent 工作区安全推送文件到 GitHub。父级 git 仓库场景下隔离 init,防止敏感配置文件、构建产物目录、其他无关项目子目录被误推。触发:用户说「上传到 GitHub」「推到 GitHub」「创建 GitHub 仓库」「备份项目到 GitHub」,或 OpenClaw 沙箱内 git push 超时需走 Contents API fallback。

Safe git push from shared workspace

适用场景
用户要求把当前目录（或其中若干文件）推到 GitHub / GitLab / Bitbucket
当前工作目录可能位于一个父级 git 仓库内（典型：OpenClaw 的 ~/.openclaw/workspace/ 本身就是 git 仓库, 里面有 .env / skills/ / node_modules/ / 其他项目目录等大量未跟踪敏感文件)
用户没有明确指定独立仓库路径
红线（必读）

不要直接在当前目录 git add . 然后 push. 父级仓库会被污染, 可能把 .env (密钥)、node_modules/ (几百 MB 噪声)、其他无关项目一起推到 GitHub, 后果包括:

私密凭证泄露（.env, .aws/, ~/.ssh/ 误包含）
仓库变噪声（几千个无关文件）
难以清理（GitHub 上推过就有 commit 历史）
工作流（4 步）
Step 1：探测当前 git 状态
cd

git rev-parse --is-inside-work-tree # true = 在某个 git 仓内
git rev-parse --show-toplevel # 真正的 git 根
git status --short | wc -l # 未跟踪文件数量
git remote -v # 是否已有远端

判断:

toplevel == target_dir → 目录本身就是独立仓库, 可直接用
toplevel ≠ target_dir → 目录在父级仓库内, 必须隔离（见 Step 2）
Step 2：隔离（父级子目录场景）

在子目录内独立 git init, 不污染父级:

cd

git init -b main # 或 master, 对齐目标平台

只 git add 你要追踪的文件（永远不要 git add .）:

git add file1 file2 file3 ... # 显式列出
git status --short # 复核

最小 .gitignore（Python 项目起步）:

pycache/ *.pyc .DS_Store
.vscode/
.idea/
.vs/ *.tmp

Step 3：创建远程仓库
gh repo create --private --description "..."

# 注：--confirm 在 gh 2.0+ 已废弃, 任何额外参数(如 --private)即跳过确认

也可走网页手动建仓, 然后 git remote add 即可.

Step 4：推送

git remote add origin https://github.com//.git
git commit -m "Initial commit: ..."
git push -u origin main

推送后用 gh repo view / --json isPrivate,pushedAt 或网页确认.

Step 5 (fallback): git push 被反复 SIGTERM 杀掉时

触发条件（必须先有 2 次以上 SIGTERM 失败才换路径, 避免误诊）:

git push 命令被 sandbox 超时中断（无错误输出就结束）

gh api repos///contents 返回 "This repository is empty" 404
本地 commit 存在, 但远端 main 分支仍是空
gh repo view ... --json pushedAt 显示的时间戳其实是 gh repo create 时的, 不是 push 成功的证据——不要被这个字段误导

原因: OpenClaw sandbox 大约 30s 杀长进程。git push 上传含图、PDF、docx 的仓库一定会超时, HTTPS / SSH / 带 token URL 三种鉴权方式都同样被杀。

修复路径: 用 GitHub Contents API (gh api -X PUT) 逐文件上传, 走普通 HTTPS POST, 单请求小不会触发超时:

# payload.json 模板（每个文件一份）

{
"message": "upload ",
"branch": "main",
"content": ""
}

# 二进制文件 (PNG/DOCX/PDF): Python 生成
python3 -c "import base64,json; print(json.dumps({'message':'upload x.png','branch':'main','content':base64.b64encode(open('x.png','rb').read()).decode()}))"

# 文本文件 (.md / .py / .json): 直接原文 (注意 JSON 字符串内换行需 \\n 转义)

gh api -X PUT repos///contents/ --input payload.json

为什么这个路径可靠:

每次单 HTTP POST, 请求体积小, 不会被 sandbox 超时杀
幂等: 重复 PUT 同一文件返回 422 no-op, 被打断的部分文件不会丢, 重跑即可补齐
不需要 git 协议, 不需要 SSH key 配置

为什么不选这些替代方案:

gh repo sync —— 要求远端已有 main 分支, 首次推送时是空仓库, 不能用
gh repo push —— 该子命令在 gh CLI 中不存在

git push https://x-access-token:TOKEN@github.com/... —— 仍走 git 协议, 同样被杀

完成后验证:

gh api repos///contents --jq 'if type == "array" then [.[].name] else .message end'

返回数组 = 推送成功; 返回 "This repository is empty" = 还没推完, 重跑脚本。

关键避坑

git add . 是高危 —— 永远显式列出要追踪的文件, 或至少用 git add 加 git status --short 复核

父级仓库探测必须做 —— git rev-parse --show-toplevel 输出不等于当前目录就是隔离信号
.gitignore 别忘 —— 至少屏蔽常见噪声: pycache/ / .DS_Store / 编辑器配置 / 大目录（node_modules/ / venv/ / .venv/ / dist/ / build/）
gh CLI --confirm 已废弃 —— 不要照旧教程写, 会报错
默认分支对齐 —— GitHub 2020 后默认 main; 老仓库可能是 master, 推送前先 git branch --show-current 看
敏感文件最后一道防线 —— 推送前 git status --short + 抽查文件列表, 确认没有 .env / *.key / secret / id_rsa 等

git push 在 OpenClaw sandbox 常被 SIGTERM 杀掉 —— 含图/PDF/docx 的仓库必超时。多次失败后改走 Step 5 的 Contents API fallback; 不要被 gh repo view --json pushedAt 的时间戳误导（那是 gh repo create 时写入的, 不是 push 成功的证据）

完整最小示例（典型场景）

# 1. 探测

cd /home/lv/.openclaw/workspace/my-project

git rev-parse --show-toplevel
# → /home/lv/.openclaw/workspace ← 与 target_dir 不同, 需隔离

# 2. 隔离
git init -b main
cat > .gitignore