Composer拉取GitLab私有包需同时满足：repositories顶层声明"type":"vcs"且url带.git后缀；auth.json严格置于全局路径（~/.composer/auth.json或%APPDATA%\Composer\auth.json）并chmod 600；域名键名与URL host完全一致；Token字段为"gitlab-token"，username为oauth2，password为完整PAT；require包名须与私有库composer.json中name字段逐字符一致。
Composer 部署私有 GitLab 仓库，不是“部署 GitLab”，而是让 Composer 能从你公司的 GitLab 拉下私有包——关键卡点从来不是网络或 Token 本身，而是 auth.json 的路径、域名键名、权限组合，以及 repositories 声明是否满足 vcs 类型约束。
auth.json 放哪？只认两个位置，其他全是白配
Composer 只在两处读 auth.json：全局路径（Linux/macOS 是 ~/.composer/auth.json，Windows 是 %APPDATA%\Composer\auth.json），或项目根目录下的 ./auth.json（但必须配合 COMPOSER_AUTH 环境变量或 --auth 参数才生效）。放在 vendor/、config/ 或子目录里，Composer 直接跳过，不报错也不提示。
-
chmod 600 ~/.composer/auth.json必须执行，否则 Composer 静默忽略整个文件 - 文件必须是合法 JSON，顶层是对象，不能有多余逗号或尾随逗号
- 域名 key 必须是纯 host，比如
"gitlab.example.com"，不能写成"https://gitlab.example.com"或"gitlab.example.com/api/v4" - 如果 GitLab 实例用了非标准端口（如
:8080），key 就得是"gitlab.example.com:8080"，和repositories.url中的 host 完全一致
gitlab-token 字段名不能错，oauth2 用户名是硬编码约定
GitLab 不接受任意字段名。Composer 认的唯一有效字段是 gitlab-token，写成 token、access_token、http-basic 全部无效。而且 username 固定填 oauth2，password 填完整的 PAT（glpat-xxxxxx），不是 token 名，也不是密码。
OpenClaw 技能 — 给定一个 GitHub 仓库 URL，自动解析出 owner/repo 名称，发现其中的 YAML/properties 配置文件及其配对的中文字段说明；在 `workspace/{repo}/` 目录下按同步日期（格式为 `YYYY-MM-DD`）创建时间戳子目录；写入 `.openclaw-config-state.json` 状态文件。每次用户提问前，先比对远程仓库当前 ref（如 `main` 或 `master`）的最新提交 SHA 与本地状态文件中记录的 SHA：
- 正确结构：
{"gitlab.example.com": {"gitlab-token": "glpat-xxxxxx"}} - 错误结构：
{"gitlab.example.com": {"token": "glpat-xxxxxx"}}→ 认不出来 - 错误结构：
{"gitlab.example.com": {"http-basic": {"username": "xxx", "password": "xxx"}}→ 这是给普通 HTTP Basic 用的，GitLab 不走这条路 - Token 必须是 Personal Access Token，Deploy Token / CI_JOB_TOKEN / OAuth App Token 全部不支持 API 调用，第一步查
/api/v4/projects/就 403
vcs 类型声明必须显式写，URL 必须带 .git 后缀
Composer 不会自动把网页 URL 转成 Git 地址，也不会扫描你访问过的域名。它只认你在 composer.json 顶层 repositories 字段里明确定义的源，且 type 必须是 "vcs"。
-
url必须是可直接git clone的地址，结尾带.git，例如："https://gitlab.example.com/group/my-pkg.git" - 漏掉
.git→ 报No valid composer.json was found -
type写成"package"或直接省略 → Composer 当这条配置不存在 - 如果 GitLab 启用了子路径（如部署在
/gitlab下），URL 中也得带上，否则 API 请求失败 - require 的包名必须和私有库
composer.json中的name字段逐字符一致，大小写、斜杠方向都不能差
Token 权限要双开：read_api + read_repository
Composer 安装分两步：先调 GitLab API 获取元数据（需要 read_api），再执行 git clone --mirror 拉代码（需要 read_repository）。缺一不可，且无法 fallback。
- 只勾
read_api→ 报403 Forbidden on /api/v4/projects/ - 只勾
read_repository→ 报Failed to download: Failed to execute git clone --mirror - 企业 GitLab 上，该 Token 所属用户还必须对目标项目有 Reporter 及以上权限
- 不要复用 CI/CD 用的 Token；建议为 Composer 单独建最小权限 Token，避免泄露风险
最常被忽略的是：即使所有配置都对，如果私有包 composer.json 里的 name 和 require 中写的不完全一致，Composer 就当它不存在——不报错，也不提示，只是静默跳过。这个细节没有日志，只能靠肉眼比对。
