什么是 TickTick 集成？

TickTick 技能在 AI 智能体与 TickTick 平台之间架起了一座坚实的桥梁，实现了任务和项目的全生命周期管理。它通过自动令牌刷新简化了复杂的 OAuth2 流程，并提供了一个旨在提高可靠性的标准化、类型化 API 客户端。通过将其纳入 Openclaw Skills，开发者可以让他们的智能体在无需人工干预的情况下，跨 TickTick 生态系统组织工作流、设定优先级并跟踪进度。

该技能基于严格的契约和错误处理机制构建，确保即使在令牌过期或达到速率限制时，您的智能体仍能保持正常运行。对于任何希望构建利用 Openclaw Skills 进行任务管理的自动化生产力助手的开发者来说，这都是一个必不可少的组件。

下载入口:https://github.com/openclaw/skills/tree/main/skills/one0x393/ticktick-calendar

安装与下载

1. ClawHub CLI

从源直接安装技能的最快方式。

2. 手动安装

将技能文件夹复制到以下位置之一

优先级：工作区 > 本地 > 内置

3. 提示词安装

将此提示词复制到 OpenClaw 即可自动安装。

TickTick 集成 应用场景

• 根据 AI 驱动的洞察或代码评审自动创建和更新任务。
• 在开发环境与 TickTick 项目之间同步项目里程碑。
• 构建需要经过身份验证且具有长期访问任务列表权限的自定义生产力机器人。
• 通过中心化的 AI 智能体界面管理团队范围内的任务分配。

1. 技能通过解析安全环境变量（如 Client ID 和 Secret）进行初始化。
2. 执行安全的 OAuth2 握手以获取访问令牌和持久刷新令牌。
3. 运行时管理令牌生命周期，在不中断智能体工作流的情况下自动刷新过期的凭据。
4. 通过 Openclaw Skills 入口执行标准化操作，如 list_tasks 或 complete_task。
5. API 响应被映射到类型化的领域模型，确保 AI 智能体接收到可预测且可操作的数据。

TickTick 集成 配置指南

要开始在 Openclaw Skills 框架内使用此技能，请按照以下步骤操作：

1. 在 .env 文件中配置您的环境变量：

• TICKTICK_CLIENT_ID
• TICKTICK_CLIENT_SECRET
• TICKTICK_REDIRECT_URI

2. 生成 OAuth 授权 URL：

npm run ticktick:cli -- auth-url

3. 将您的回调 URL 交换为本地令牌文件：

npm run ticktick:cli -- auth-exchange --callbackUrl "YOUR_CALLBACK_URL"

4. 通过列出您的项目来验证连接：

npm run ticktick:cli -- list-projects

TickTick 集成 数据架构与分类体系

该技能使用结构化的元数据分类和凭据的本地持久化来组织其数据。这对于维护 Openclaw Skills 内部的状态至关重要。

name: ticktick
description: "TickTick task/project integration toolkit for OAuth2 authorization, token refresh, and typed task/project operations. Use when users need to authenticate with TickTick, run task/project CRUD workflows, or operate the OpenClaw/Codex wrapper via token.json."
metadata: {"openclaw":{"requires":{"env":["TICKTICK_CLIENT_ID","TICKTICK_CLIENT_SECRET","TICKTICK_REDIRECT_URI"]},"primaryEnv":"TICKTICK_CLIENT_SECRET"}}

TickTick Skill

Operate TickTick task/project workflows with strict contracts, runtime token management, typed API access, and OpenClaw-ready action wrappers.

Quick Reference

Capabilities

• OAuth2 contract + runtime token client
  • Authorization URL build/callback parse
  • Authorization-code exchange
  • Refresh-token renewal
• Typed API client with timeout/retry/error typing
  • HTTP timeout and exponential backoff for retryable failures
• Core usecases (MVP 5)
  • create_task
  • list_tasks
  • update_task
  • complete_task
  • list_projects
• OpenClaw/Codex wrapper entrypoints
  • skill-entry/token-manager.mjs
  • skill-entry/ticktick-skill.mjs
  • scripts/ticktick-cli.mjs

Prerequisites

Required environment variables:

• TICKTICK_CLIENT_ID
• TICKTICK_CLIENT_SECRET
• TICKTICK_REDIRECT_URI

Optional runtime defaults:

• TICKTICK_OAUTH_AUTHORIZE_URL (default: https://ticktick.com/oauth/authorize)
• TICKTICK_OAUTH_TOKEN_URL (default: https://ticktick.com/oauth/token)
• TICKTICK_API_BASE_URL (default: https://api.ticktick.com/open/v1)
• TICKTICK_API_TIMEOUT_MS (default: 10000)
• TICKTICK_API_MAX_RETRIES (default: 3)
• TICKTICK_API_RETRY_BASE_DELAY_MS (default: 250)
• TICKTICK_OAUTH_SCOPE
• TICKTICK_USER_AGENT

Token and notification options:

• TICKTICK_TOKEN_PATH (default: ~/.config/ticktick/token.json)
• TICKTICK_REAUTH_WEBHOOK_URL
• TICKTICK_REAUTH_NOTIFY_COOLDOWN_MS
• TICKTICK_REAUTH_NOTIFY_STATE_PATH

OpenClaw Setup (Recommended)

OpenClaw integration is provided through createTickTickOpenClawSkill in skill-entry/ticktick-skill.mjs.

Skill action surface

Expose the following actions:

• create_task
• list_tasks
• update_task
• complete_task
• list_projects

Runtime/token behavior

1. Parse env via parseTickTickEnvFromRuntime.
2. Resolve token path (options.tokenPath -> TICKTICK_TOKEN_PATH -> default path).
3. Load access token with auto refresh (getAccessTokenWithAutoReauth).
4. On missing/expired token without valid refresh token:
   • raise ReauthRequiredError
   • optionally notify via webhook
   • surface reauthorization URL to caller.

CLI Workflow (Practical)

1) Generate OAuth URL

npm run ticktick:cli -- auth-url

2) Exchange callback for token file

npm run ticktick:cli -- auth-exchange --callbackUrl "http://localhost:3000/oauth/callback?code=...&state=..."

3) Run actions

npm run ticktick:cli -- list-projects
npm run ticktick:cli -- list-tasks --projectId  --limit 20
npm run ticktick:cli -- create-task --projectId  --title "Write docs" --priority 3
npm run ticktick:cli -- update-task --taskId  --priority 5
npm run ticktick:cli -- complete-task --taskId 

Programmatic Workflow

1. Load env: parseTickTickEnvFromRuntime()
2. Build runtime: createTickTickRuntime({ env, getAccessToken })
3. Execute usecases via runtime.useCases.*
4. Handle category-mapped errors in caller for retry/UX behavior
5. Persist/rotate token outside process memory when used in production

Error Mapping Contract

Normalize API/runtime errors to domain categories:

Verification Gates

Run after any implementation or integration change:

npm run typecheck
npm test

If either gate fails, do not finalize until fixed or explicitly accepted by user.

Troubleshooting

Token file not found

• Symptom: ReauthRequiredError with message about missing token file
• Action: run auth-url -> complete browser consent -> run auth-exchange

Token expired and refresh unavailable

• Symptom: runtime/CLI asks for reauthorization URL
• Action: complete OAuth again and persist new token JSON

401/403 on valid token

• Verify OAuth app scopes and redirect URI alignment
• Confirm .env values match TickTick app configuration

429/5xx spikes

• Check retry settings:
  • TICKTICK_API_MAX_RETRIES
  • TICKTICK_API_RETRY_BASE_DELAY_MS
• Add higher-level caller backoff if workload is bursty

References

• README.md
• docs/openclaw-skill-guide.md
• skill-entry/token-manager.mjs
• skill-entry/ticktick-skill.mjs
• scripts/ticktick-cli.mjs
• src/core/ticktick-runtime.ts
• src/core/ticktick-usecases.ts
• src/api/ticktick-api-client.ts
• src/api/ticktick-gateway.ts
• src/shared/error-categories.ts