TickTick Skill#

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

Quick Reference#

SituationActionFirst-time OAuth authorization neededRun npm run ticktick:cli -- auth-url, then auth-exchange with callback URLToken expired but refresh token existsUse runtime/CLI auto-refresh path ( getAccessTokenWithAutoReauth)Token missing or refresh failedReauthorize from emitted URL and rerun commandNeed task creation/update/completeUse runtime.useCases.createTask/updateTask/completeTask or skill actionsNeed task/project listingUse runtime.useCases.listTasks/listProjects or CLI commandsNeed OpenClaw action integrationUse skill-entry/ticktick-skill.mjs and expose 5 MVP actionsNeed error categorization for UX/retryHandle TickTickDomainError categories from src/shared/error-categories.ts

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#

bash

npm run ticktick:cli -- auth-url

2) Exchange callback for token file#

bash

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

3) Run actions#

bash

npm run ticktick:cli -- list-projects
npm run ticktick:cli -- list-tasks --projectId <projectId> --limit 20
npm run ticktick:cli -- create-task --projectId <projectId> --title "Write docs" --priority 3
npm run ticktick:cli -- update-task --taskId <taskId> --priority 5
npm run ticktick:cli -- complete-task --taskId <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:

CategoryTypical Sourceauth_401Invalid/expired access tokenauth_403Scope/permission deniednot_found_404Missing task/project resourcerate_limit_429TickTick rate-limited requestserver_5xxTickTick server-side failurenetworkTimeout, transport, DNS, fetch failuresvalidationInput contract or payload mismatchunknownNon-classified fallback

Verification Gates#

Run after any implementation or integration change:

bash

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