1. 先别急着改代码这个报错根本不是网络问题! [remote rejected] master - master (pre-receive hook declined)这行字第一次看到的人十有八九会往网络、SSH、代理方向想。我当初也是反复ping服务器、重配 SSH key折腾半天才发现方向完全错了。先说清楚它是什么这是 Git 服务端在接收推送之前由服务端的pre-receive钩子主动拒绝了你。注意关键词是「服务端拒绝」不是「连不上」。也就是说你的网络、凭据、SSH 握手可能全都是通的代码也传到了服务端只是服务端在最后一步说「这个分支你不能推」。它能做什么判断pre-receive钩子是 GitLab、Gitea、GitHub Enterprise 这类平台用来做分支保护、权限校验、提交规范检查的入口。你推master被拒最常见的原因就是你的账号角色比如 Developer默认没有直接推送受保护分支master的权限。适合谁看刚接手公司仓库、被拉进 GitLab 项目组、本地能 clone 但一 push 到 master 就报这个错的人。这篇我会从服务端钩子、分支保护、本地凭据三条线拆开定位再给一套可复制的配置骨架用统一的 Key/API 通道把推送链路验证一遍让你能自己确认拒绝到底来自哪一层。2. 三条线定位钩子、保护、凭据遇到这个报错别乱试。按下面三条线依次排查基本 5 分钟内能锁定来源。2.1 服务端钩子线pre-receive是服务端脚本。它拒绝你的原因可能是分支保护也可能是自定义的提交信息校验比如要求 commit message 带 Jira 号、文件大小限制、禁止 force push 等。你本地看不到钩子内容只能通过平台界面或管理员确认。2.2 分支保护线这是最高频的原因。GitLab 里master或main通常被设为 Protected Branch默认只有 Maintainer 及以上能直接 pushDeveloper 只能通过 Merge Request 合并。你如果是 Developer 角色直接git push origin master必然被拒。2.3 本地凭据线有时候你用的是旧账号的凭据或者 HTTPS 缓存了错误 token服务端识别出的身份权限不够也会走到同一个报错。这条线容易被忽略因为报错文案和权限不足一模一样。三条线的判断顺序建议是先看平台分支保护设置 → 再看自己账号角色 → 最后清本地凭据重试。下面给具体操作。3. 可复制配置骨架config.toml 与 settings.json排查过程中我习惯用一个统一的 API 通道来验证「我的凭据到底能不能通过服务端校验」避免在 Git 层反复试错。这里给出两份骨架配置你可以直接复制改。3.1 config.toml 骨架这份配置用于统一管理模型/API 通道的 Key方便在排查脚本里复用同一个凭据来源# config.toml [default] # 统一 API 入口所有请求走这里 base_url https://taotoken.net/api # 你的统一 Key从控制台生成 api_key sk-你的Key # 请求超时排查时设短一点方便快速失败 timeout_ms 15000 [git_check] # 用于验证推送链路的仓库地址 remote origin branch master # 是否在推送前做一次 dry-run dry_run true3.2 settings.json 骨架如果你在编辑器或 Agent 环境里做验证用这份{ api: { baseUrl: https://taotoken.net/api, apiKey: sk-你的Key, model: claude-sonnet }, git: { remote: origin, protectedBranch: master, pushMode: merge-request }, verify: { dryRun: true, timeoutMs: 15000 } }Key 的生成入口在控制台路径是console生成后到api-keys页面复制。这两份骨架的作用是把「凭据」和「推送目标」集中在一处排查时改一个地方就能复现不用在多个终端里翻历史命令。注意dry_run true时不会真正推送只做连通性和权限预检适合排查阶段反复跑。4. 验证请求确认拒绝来自哪一层配置好了接下来分三步验证。每一步都给出命令和预期结果。4.1 验证 API 通道是否通先用统一 Key 打一次模型对话接口确认凭据本身有效curl -s -X POST https://taotoken.net/api/v1/chat/completions \ -H Authorization: Bearer sk-你的Key \ -H Content-Type: application/json \ -d { model: claude-sonnet, messages: [{role: user, content: ping}] }预期返回一段正常的 JSON带choices字段。如果这里就 401说明 Key 本身有问题跟 Git 无关先去api-keys重新生成。4.2 验证 Git 远端身份git remote -v git config --get user.email git config --get user.name确认remote指向的仓库是你有权限的那个user.email是平台能识别的账号邮箱。很多人 push 被拒是因为本地user.email是私人邮箱平台匹配不到团队成员身份。4.3 用 dry-run 预检推送git push --dry-run origin master--dry-run会走完整个服务端校验流程但不真正写入。如果这里就报pre-receive hook declined那 100% 是服务端权限/保护规则问题跟本地网络无关。如果 dry-run 通过但真实 push 失败才需要看本地凭据缓存。成功的结果长这样To https://your-gitlab.com/group/repo.git * [new branch] master - master或者 dry-run 模式下显示Everything up-to-date且无 rejected 字样。5. 本篇常见错排查下面这几个坑我基本每次带新人都要讲一遍。坑一以为换个分支名就能推。有人把master改成main再推照样被拒因为保护规则可能同时覆盖了两个名字。正确做法是推一个特性分支然后走 Merge Request。坑二清了 SSH key 但没清 HTTPS 缓存。如果你用的是 HTTPS 方式凭据存在系统钥匙串里。macOS 用git credential-osxkeychain eraseWindows 在「凭据管理器」里删对应条目。清完再 push 会重新提示输入账号密码/token。坑三token 权限范围不够。用 Personal Access Token 时必须勾选write_repository权限。只勾了read_repository的话clone 能成功push 必被拒报错文案和权限不足一样。坑四分支保护允许 Maintainer但你是 Developer。这是最典型的。去项目 Settings → Repository → Protected Branches 看一眼master的 Allowed to push 是谁。如果是 Maintainer你就老老实实开 MR。坑五pre-receive 里有自定义提交校验。有些团队要求 commit message 带任务号格式不对也会被同一个钩子拒。这种要看管理员给的规范文档本地用git commit --amend改信息后重推。排查顺序总结成一句先--dry-run确认是不是服务端拒再去平台看保护规则和角色最后才动本地凭据。6. 后续接入与长期使用建议把这次排查跑通之后如果你经常需要在多个仓库、多个环境之间切换建议把凭据和 API 通道统一管理起来别每个项目配一套。统一 Key 的好处是排查时只改一处验证链路时也只验一处。具体分流一下如果你是在做接入和排障重点看 API Keys 和接入文档把 Key 生成、权限范围、base_url 这三样对齐。如果你要验证模型通道是否正常直接用模型对话页面打一次请求确认返回正常再回到 Git 排查。如果你是长期写代码、跑 Agent建议用 Coding Plan把额度、模型、通道固定下来避免每次临时配。我自己的习惯是新项目初始化时先把config.toml和settings.json两份骨架拷进去Key 从控制台统一生成然后git push --dry-run跑一遍预检。这样后面无论换仓库还是换分支出问题都能快速定位到是钩子、保护规则还是凭据。