twingate-api

角色

此技能负责 Twingate 的 GraphQL API、服务账户密钥管理、CLI 工具和 API 驱动的自动化。涵盖脚本编写、CI/CD 流水线集成、分页、速率限制、令牌权限设置，以及以编程方式配置 Connector 和服务账户凭据的流程。它不能替代 IaC——可用于脚本编写和自动化，不适用于管理需要生命周期跟踪的长期 Twingate 对象。

决策与指南

• 读取 mutation 响应中的 entity 前，务必先检查 ok。 mutation 可能返回 HTTP 200，但 ok: false 且 entity: null。未先检查 ok 就读取实体字段，会导致空引用错误或静默的数据损坏。失败时，请检查 error.errorCode 和 error.message。
• 务必分页，切勿假设所有结果都能放在一页中。 忽略分页的脚本会静默遗漏记录，且不会报错。你可能只获取到 500 个资源中的 50 个。循环检查 pageInfo.hasNextPage，直到其为 false；每次请求都将 pageInfo.endCursor 作为 after 参数传入。
• 切勿解析、解码或构造 ID。 Twingate ID 是不透明的、经过 base64 编码的 NodeID。只能使用 API 返回的 ID。切勿通过解码 base64 来推断数字组成部分。
• 为任务签发权限最小的令牌。 监控和报告使用 Read 权限；配置资源使用 Write 权限。仅在调用 connectorGenerateTokens 和生成服务账户密钥时使用 Provision 权限。切勿给只读脚本签发 Provision 级别的令牌。
• connectorGenerateTokens 会轮换现有 Connector 的凭据。 在已部署的 Connector 上再次调用会使当前令牌失效；在使用新令牌重启之前，Connector 会停止工作。仅在重新配置凭据时调用，切勿将其用作“刷新”操作。
• 持久化配置管理优先使用 Terraform 或 Pulumi，而非原始 GraphQL。 API 适用于脚本编写、自动化和报告。对于需要生命周期跟踪和漂移检测的长期 Twingate 对象，IaC 更合适。
• 从一开始就实现带 Retry-After 退避的 429 重试，切勿事后补上。 API 会强制执行每分钟速率限制。忽略 429 的脚本在执行大型操作时会中途失败。Terraform 和 Pulumi provider 会自动处理此问题，原始脚本则必须自行处理。
• 服务账户密钥会过期；任何使用这些密钥的流水线都必须内置轮换逻辑。 监控 expiresAt，并在过期前轮换。失败后才进行响应式轮换会中断流水线。
• 有两个互不相关的工具都叫“Twingate CLI”，切勿混为一谈。 Twingate-Labs/tg-cli（Deno/TypeScript；导出/导入、拓扑图）和 Twingate-Labs/Twingate-CLI（Python，安装为 tgcli；完整 CRUD、多租户会话）是两个独立项目，使用不同的标志，且没有共同的历史。提供命令语法前，先确认用户指的是哪个。推荐在生产环境中使用 gh-twingate-solutions-general-scripts.md 等代码库前，先说明它们是由 LLM 辅助编写的参考示例，而非受支持的产品。

首先搜索参考资料

回答前，先用用户自己的关键词搜索 references/，并引用找到的内容。 文件名只能揭示主题——工具名称、供应商名称以及精确的标志／环境变量名称都在文件正文中，因此仅扫描文件名会遗漏这些信息：

grep -ril "cloudwatch" references/     # -> gh-twingate-labs-tg-aws-tag-sync.md
grep -ril "graphviz" references/       # -> gh-twingate-labs-tg-cli.md
grep -ril "jupyter" references/        # -> gh-twingate-labs-twingate-api-intro-with-python.md, gh-twingate-solutions-health-report-generator.md

在编写任何 API 代码或回答涉及以下任一内容的问题之前，先阅读 references/graphql-schema-reference.md——这是权威的类型和字段参考，处理任何非简单查询或变更时都必须查阅：

• 精确的查询／变更名称、参数名称或参数类型
• 响应对象上的字段名称（包括嵌套字段和分页结构）
• 任意字段的枚举值（例如，资源协议枚举、地址类型枚举）
• 创建／更新变更的输入类型结构
• 某个字段是否存在、是否可为空或是否已弃用

对于命令行工具（Python tgcli、Deno tg-cli、tgcli-web、OpenClaw），建议使用命令前，先阅读相应的命令行参考——不同工具的标志名称和子命令结构各不相同，其中两个工具的名称几乎相同。

不要根据训练数据中的记忆回答有关架构或命令行的问题——架构会不断演进，命令行工具也有特定版本的语法。如果用户询问是否有工具可用于某项自动化任务（AWS 标签同步、健康报告、CI 运行器访问），请先搜索，再说没有。

路由

协同激活，不要二选一。 以下指引是累加的：对于跨领域提示，除了当前技能之外，还要加载并搜索指定技能的 references/——绝不要停留在第一个匹配的技能。先用用户自己的关键词搜索相关技能的参考资料；如果搜索命中，再完整加载。Twingate 的答案通常分散在多个技能中，因此应倾向于多查，而不是少查。此处常见的跨领域组合包括：自动化某种对象 → 同时查阅该对象对应的技能（connectors／identity／architect）；持久化生命周期管理 → terraform／pulumi。

• → twingate-terraform / twingate-pulumi：当用户需要持久化 IaC 管理，而非 API 脚本时——IaC 可提供漂移检测、审计跟踪和生命周期管理，而原始 API 脚本无法提供这些能力
• → twingate-architect：在编写针对资源、远程网络、群组和连接器的 API 自动化之前，用于了解它们是什么
• → twingate-connectors：涉及 connectorGenerateTokens 的上下文时——令牌配置是一项 API 操作，但连接器部署的具体细节（运行时环境变量、重启行为）见 twingate-connectors

参考资料

请参阅 references/，其中包含每周更新的当前资料库。目录中有两类文件，此外还有一份人工维护的权威参考资料：

• graphql-schema-reference.md — 静态 GraphQL SDL，由人工维护，具有权威性。绝不自动重新生成。
• {slug}.md — 对 twingate.com/docs 页面（产品文档）的摘要。
• gh-{org}-{repo}.md — 对公开 Twingate GitHub 仓库的摘要：官方工具、SE 自动化和社区集成。

如果用户询问……	首先阅读
查询/变更签名、字段名称、枚举值、输入类型	graphql-schema-reference.md（权威参考资料）
API 概览、身份验证、入门指南	api-overview.md、api.md、getting-started-with-the-api.md
探索 API、示例查询	exploring-the-apis.md
Python CLI 文档页面（tg-cli）	introduction-to-the-python-cli.md
JavaScript CLI 文档页面（tg-cli）	introduction-to-tg-cli-javascript.md
OpenClaw 自动化工具（通用、Docker Compose、DigitalOcean）	openclaw.md、openclaw-docker-compose.md、openclaw-digitalocean.md
CI/CD 流水线模式（文档页面）	example-cicd-configurations.md
用于 CI 运行器的 GitHub Action — 通过 Service Key 在运行器上安装 Client，以便工作流步骤访问受 IP 限制/私有资源	gh-twingate-github-action.md
由 AWS 标签驱动的资源自动化（EC2、ECS、RDS 上的 tg_resource/tg_groups 标签 → Lambda 通过 EventBridge/CloudWatch Events 创建/删除 Twingate 资源）	gh-twingate-labs-tg-aws-tag-sync.md
Deno/TypeScript 管理 CLI（tg-cli）— 将拓扑导出为 Excel/PNG（GraphViz），导入组/网络/资源	gh-twingate-labs-tg-cli.md
Python CLI 的浏览器 Web UI（tgcli-web）— 封装 tgcli 库的 FastAPI 应用；实体浏览、带差异审核的导出/导入、运行状况仪表板，以及 Docker/K8s/pip 安装	gh-twingate-labs-tgcli-web-py.md
GraphQL API 的 Jupyter/Python 入门教程 — 查询、变更、内省，不要求具备 GraphQL 相关知识	gh-twingate-labs-twingate-api-intro-with-python.md
Python 管理 CLI（基于 Typer 的 tgcli）— 对远程网络/资源/连接器/组/用户/服务账户进行完整 CRUD 操作、多租户会话，以及 Synced→Manual 组迁移	gh-twingate-labs-twingate-cli.md
通用运维脚本（客户端部署、Intune/Autopilot、将网关用作 DNS 服务器、Network Events CSV 筛选、批量移除组）— 由 LLM 辅助生成的参考示例，并非受支持的产品	gh-twingate-solutions-general-scripts.md
网络运行状况/洞察报告生成器 — Jupyter notebook，可将 Network Events 导出数据转换为资源/用户/连接器/远程网络运行状况分析	gh-twingate-solutions-health-report-generator.md

此表仅供快速查找，并未涵盖整个资料库——如果问题与表中条目不匹配，请先在 references/ 中使用 grep 搜索再作答。默认先检查架构——切勿凭记忆编写查询或变更；字段名称和枚举值会发生变化。