Metadata

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

Situation	Action
First-time OAuth authorization needed	Run `npm run ticktick:cli -- auth-url`, then `auth-exchange` with callback URL
Token expired but refresh token exists	Use runtime/CLI auto-refresh path (`getAccessTokenWithAutoReauth`)
Token missing or refresh failed	Reauthorize from emitted URL and rerun command
Need task creation/update/complete	Use `runtime.useCases.createTask/updateTask/completeTask` or skill actions
Need task/project listing	Use `runtime.useCases.listTasks/listProjects` or CLI commands
Need OpenClaw action integration	Use `skill-entry/ticktick-skill.mjs` and expose 5 MVP actions
Need error categorization for UX/retry	Handle `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

Parse env via parseTickTickEnvFromRuntime.
Resolve token path (options.tokenPath -> TICKTICK_TOKEN_PATH -> default path).
Load access token with auto refresh (getAccessTokenWithAutoReauth).
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 <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

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

Error Mapping Contract

Normalize API/runtime errors to domain categories:

Category	Typical Source
`auth_401`	Invalid/expired access token
`auth_403`	Scope/permission denied
`not_found_404`	Missing task/project resource
`rate_limit_429`	TickTick rate-limited request
`server_5xx`	TickTick server-side failure
`network`	Timeout, transport, DNS, fetch failures
`validation`	Input contract or payload mismatch
`unknown`	Non-classified fallback

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

ticktick-calendar

安装技能