核心用法
ClickUp Skill 通过 Maton 代理服务提供对 ClickUp 官方 API 的完整访问能力，采用托管式 OAuth 2.0 认证方案。用户仅需配置 MATON_API_KEY 环境变量，即可通过 https://api.maton.ai/clickup/{native-api-path} 端点调用 ClickUp 原生接口，无需直接处理 ClickUp OAuth 的令牌刷新与密钥管理。
该 Skill 覆盖 ClickUp 完整的数据层级结构：Workspace（Team）→ Space → Folder → List → Task，支持对任务、列表、文件夹、空间、工作区、用户资料及 Webhook 的 CRUD 操作。典型工作流包括：查询团队任务列表、创建带优先级和截止日期的任务、批量更新任务状态、配置实时事件 Webhook 等。
认证流程采用双重机制：Maton API Key 作为网关层身份凭证，ClickUp OAuth 作为应用层授权。用户需先在 Maton 平台创建 ClickUp 连接，通过浏览器完成 OAuth 授权后，代理服务会自动注入令牌。多账户场景下可通过 Maton-Connection 头部指定特定连接。
显著优点
托管式 OAuth 降低集成门槛：开发者无需自建 OAuth 应用、处理令牌刷新逻辑或存储敏感凭证，Maton 代理层自动管理 ClickUp 令牌生命周期。
完整 API 覆盖：支持 ClickUp v2 API 的全功能，包括复杂查询参数（按状态/负责人/日期过滤）、分页、子任务、自定义字段、时间追踪等企业级特性。
Webhook 原生支持：可订阅 20+ 种事件类型（任务创建/更新/删除、状态变更、评论、时间追踪等），实现实时工作流触发。
多语言示例完备：文档提供 Bash/Python/JavaScript/curl 等多种调用示例，降低接入成本。
潜在局限
代理层单点依赖：所有请求需经过 Maton 代理服务（api.maton.ai），若该服务不可用将完全中断 ClickUp 访问，形成供应商锁定风险。
网络延迟增加：相比直连 ClickUp API，请求需额外经过代理跳转，可能增加 50-200ms 延迟，对高频实时场景有一定影响。
权限粒度较粗：OAuth 授权范围为完整工作空间级别，无法针对单个 Space 或 List 进行细粒度权限控制。
写操作需人工确认：文档明确"所有写操作需要显式用户批准"，这在自动化脚本场景中可能成为障碍。
适合人群
- 希望快速集成 ClickUp 但不想投入 OAuth 开发成本的小型团队
- 需要将 ClickUp 数据同步至内部系统的后端开发者
- 构建跨平台工作流自动化的 DevOps/效率工程师
- 使用 Python/JavaScript 进行数据分析或报告生成的技术人员
常规风险
| 风险类别 | 具体描述 | 缓解建议 |
|---------|---------|---------|
| 密钥泄露 | `MATON_API_KEY` 若被硬编码或日志泄露，攻击者可访问全部 ClickUp 数据 | 使用密钥管理服务，避免提交至版本控制 |
| 代理服务安全 | Maton 作为第三方代理，理论上可访问传输中的任务数据 | 评估 Maton 安全合规资质，敏感业务考虑直连方案 |
| 误操作数据丢失 | 批量删除任务/空间操作不可逆 | 写操作前强制二次确认，定期导出备份 |
| 速率限制 | ClickUp API 存在 100 req/min 限制，超额将触发 429 错误 | 实现指数退避重试，监控响应头 |
| Webhook 端点安全 | 若 webhook 端点未验证签名，可能接收伪造事件 | 验证 `secret` 字段，使用 HTTPS 端点 |