GitHub 部署密钥路由

将 GitHub 私有仓库访问视为一个路由问题，而不仅仅是一个 Git 问题。

核心规则

• 除非明确选择使用机器用户（machine user），否则每个私有仓库应使用唯一的部署密钥（deploy key）。
• 每个密钥应对应一个唯一的 SSH 主机别名（SSH host alias）。
• 每个仓库的 remote 必须显式指向正确的主机别名。
• 当存在多个部署密钥时，切勿依赖通配型 Host github.com 规则。
• 验证顺序应为：先验证 SSH 连接，再验证 Git 协议，最后执行 push 操作。
• 若涉及自动化流程，请同步修复实际生效的仓库 remote 和生成/写入该 remote 的配置文件或脚本源码。

标准模式

Host github.com-backup
    HostName github.com
    User git
    IdentityFile ~/.ssh/openclaw_backup_ed25519
    IdentitiesOnly yes

git remote set-url origin git@github.com-backup:OWNER/REPO.git

当机器上存在多个私有 GitHub 仓库、多个 SSH 密钥，或任何重复运行的 GitHub 自动化任务时，请使用此方法。

快速排查流程

如需最快定位路径：

1. 阅读 references/symptoms.md，精确匹配报错信息。
2. 阅读 references/patterns.md，比对当前使用的主机别名与 remote 配置结构。
3. 仅当身份模型（identity model）本身尚未确定时，才阅读 references/decision-guide.md。
4. 仅当脚本、备份流程或配置值可能重写 remote 时，才阅读 references/openclaw-automation.md。

工作流程

1. 确认实际正在使用的仓库与 remote

检查本地仓库路径、当前配置的 remote，并确认失败操作的来源：

• 交互式执行的仓库命令
• 备份/同步脚本
• 存储仓库 URL 的配置文件
• cron 或其他自动化任务

若仓库路径与配置来源不一致，则不应将其视为同一问题进行修复。

2. 定位密钥路由层

查阅 references/patterns.md 了解标准主机别名布局； 当涉及操作系统特定的密钥路径，或 Windows / WSL / macOS 行为差异时，请查阅 references/key-storage-by-system.md。

请自问：

• 当前仓库使用的是哪个 SSH 主机别名？
• 该别名实际加载的是哪一把密钥？
• 该密钥是否已在 GitHub 上被授权用于此仓库？
• 是否存在宽泛的 Host github.com 规则劫持了连接流量？

3. 根据症状诊断

在修改任何配置前，请先阅读 references/symptoms.md 并精确匹配错误字符串。

4. 选择合适的身份模型

当用户需在以下选项间做决策时，请阅读 references/decision-guide.md：

• 部署密钥（deploy key）
• 个人 SSH 密钥（personal SSH key）
• 机器用户（machine user）

当问题实质在于“SSH 路由的边界在哪里、GitHub API 权限又从何处开始”时（尤其适用于 PR 合并自动化、发布创建、细粒度 PAT 与 deploy key 的取舍等场景），请查阅 references/identity-model-boundaries.md。

5. 检查自动化导致的配置漂移

当该仓库被 OpenClaw 备份/恢复流程、插件、cron 任务或配置驱动的工作流所使用时，请查阅 references/openclaw-automation.md。

6. 按安全顺序修复

1. 修复或新增 SSH 主机别名。
2. 使用 ssh -G 验证配置解析是否正确。
3. 使用 ssh -T git@ 测试 SSH 连通性与认证。
4. 更新仓库的 remote URL。
5. 更新所有仍会写入旧 remote 的配置文件或脚本源码。
6. 使用 git ls-remote origin 验证远程引用可正常获取。
7. 仅在此之后执行 push 或 pull 操作。

最小命令集

ls -la ~/.ssh
sed -n '1,200p' ~/.ssh/config
git remote -v
ssh -G  | sed -n '1,40p'
ssh -T git@
git ls-remote origin

配套脚本

对单个本地仓库执行只读审计，请运行：

scripts/audit-routing.sh /path/to/repo

该脚本汇总输出以下信息：

• 仓库的 remote 列表
• 从 origin 推断出的 SSH 主机别名
• ~/.ssh 目录下的文件及其权限
• ~/.ssh/config 文件的预览片段
• 针对检测到的别名执行 ssh -G 的摘要输出

建议在编辑配置前先运行该脚本进行检查。

需要上报的内容

• 用一句话说明根本原因
• 明确失败是源于本地配置、GitHub 权限，还是二者兼有
• 给出最小化的修复方案
• 精确描述所有已变更项