1. 基本信息
| 项目 | 内容 |
|---|---|
| 名称 | api-gateway-troubleshooting-google-skills |
| 作者/维护者 | Google(官方) |
| 来源链接 | https://github.com/google/skills/tree/main/skills/cloud/api-gateway-troubleshooting |
| 许可证 | Apache-2.0 |
| GitHub Stars / Forks | 21,805 / 1,861(所属仓库整体数字,不代表本技能自身热度;GitHub API,2026-11-11 读取) |
| 最新版本 | 技能内标注 1.0.0;仓库主分支最近一次提交 2026-11-06 |
| 安装方式 | 把技能目录复制进 agent 的 skills 目录;命令经 gcloud 执行 |
数据来源:上述数字取自 GitHub API;功能与评分依据来自技能正文与官方文档。
2. 功能介绍与亮点
一句话:网关调不通时按症状分流——4xx/5xx、429 配额、超时、CORS 预检、还是配置创建失败,各有一条查法。
- 按现象归因:请求失败、超时、预检失败、配置创建或网关更新失败,分别对应不同的排查路径。
- 配额与限流:429 与其他配额错误先分清是网关配额还是后端限流。
- CORS 预检:预检失败时看的是网关配置还是后端响应头。
- 部署期错误:
api-configs create、gateways create/update失败时的服务账号、并发与限额原因。 - 自定义域与 TLS:绑定域名或证书排查时,先确认问题在网关侧。
- 边界清楚:Apigee、Cloud Endpoints、GKE Gateway 都不在范围内,OpenAPI 语法错误交给对应技能。
3. 适用场景
所属分类:集成与工作流自动化。
- 网关突然返回 429、分不清是配额还是后端限流的运维;
- 前端报 CORS、需要判断是网关还是后端问题的全栈;
api-configs create失败、要快速看服务账号与限额的工程师;- 排查自定义域与证书问题时想先排除网关侧的 SRE。
4. 跨 Agent 兼容性
| Agent | 结论 | 依据 |
|---|---|---|
| Claude Code | 原生支持 | 技能目录安装,按描述触发 |
| Codex | 需适配 | 技能正文通用,gcloud 调用需按平台调整 |
| OpenClaw | 需适配 | 需要平台支持技能目录并允许执行本地命令 |
| Hermes Agent | 未验证 | 未找到该平台的接入示例 |
5. 推荐理由
网关故障的麻烦在于「同一个 4xx 有一堆可能的原因」,而排查顺序决定了要翻几轮日志。这份技能按现象把可能性压到少数几条,并明确哪些属于配置语法问题、该转给谁——对半夜被 429 叫起来的人,这比从文档第一页读起有用。
6. 评分
| 维度 | 分数 | 说明 |
|---|---|---|
| 受欢迎程度 | 7 | Google 官方出品;所属仓库 21,805 stars 是整个合集热度,不代表本技能自身热度 |
| 可用性 | 8 | 现象到原因的映射清楚、边界明确;前置是 gcloud 与网关项目 |
| 安全性 | 9 | 见下方清单;官方开源,只读诊断为主 |
安全性检查清单:
| 项 | 结果 |
|---|---|
| ① 执行 shell 与权限 | 通过 gcloud 读取网关状态与配置,作用域限于所给项目 |
| ② 联网外发 | 只与 Google Cloud 端点通信 |
| ③ 凭据 | 使用既有 gcloud 凭据,不要求写进对话 |
| ④ 可疑指令 | 未见注入或夹带推广 |
| ⑤ 作者信誉 | Google 官方仓库,Apache-2.0 |
| ⑥ License | Apache-2.0,全文可查 |
| ⑦ 维护时间 | 2026-11-06 仍在更新 |
扣分点:需要真实网关与项目;后端问题仍需后端日志确认。
7. 跟同类 Skills 相比的优势
| 技能 | 定位 | 与本技能的差异 |
|---|---|---|
| api-gateway-openapi-spec-authoring-google-skills | 规格编写与迁移 | 管「规格写对」;本技能管「跑不通时查哪」 |
| api-gateway-backend-security-and-rate-limiting-google-skills | 后端封锁与限流 | 管安全配置;本技能管故障归因 |
| api-gateway-mcp-server-google-skills | 把 API 发布成 MCP 工具 | 管 agent 接入;本技能管网关本身 |
核心差异:同类分别管规格、安全与接入,它专治「网关跑不通」这一类现场问题。
8. 用户评价
该技能目前在第三方平台尚无具名用户评价(2026-11-11)。
9. 其他补充
- 技能内标注 1.0.0,随官方仓库更新。
- 属于
google/skills合集(180 个技能),可按需只装这一条。
10. 安装使用方式
git clone https://github.com/google/skills
mkdir -p ~/.claude/skills
cp -r skills/skills/cloud/api-gateway-troubleshooting ~/.claude/skills/
装好后说「网关这接口一直 429,帮我分清是配额还是后端限流」,它会按现象给出排查顺序。
11. 注意事项
- 先收集请求时间、状态码与网关名,结论会更准。
- 429 可能是网关配额,也可能是后端限流,两边都要看。
- OpenAPI 语法错误交给规格编写技能,别在这里绕。
- 需要项目访问权限。