OpenSkillIndex← back to search
claude-code

Openakita openakita/skills@todoist-task

Manage Todoist tasks, projects, sections, labels, and filters via REST API v2. Supports task CRUD, due dates, priorities, recurring tasks, project organization, and advanced filtering. Based on doggy8088/agent-skills/todoist-api, using curl + jq.

install
source · Clone the upstream repo
git clone https://github.com/openakita/openakita
Claude Code · Install into ~/.claude/skills/
T=$(mktemp -d) && git clone --depth=1 https://github.com/openakita/openakita "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/todoist-task" ~/.claude/skills/openakita-openakita-openakita-skills-todoist-task && rm -rf "$T"
manifest: skills/todoist-task/SKILL.md
source content

Todoist Task — Todoist 任务管理

When to Use

  • 用户需要创建、查看、更新或删除 Todoist 任务
  • 需要管理 Todoist 项目和分区
  • 需要设置任务优先级、截止日期、重复规则
  • 需要用标签分类任务
  • 需要查询和过滤任务
  • 需要将对话中讨论的待办事项同步到 Todoist
  • 需要批量管理任务（导入/导出/整理）

Prerequisites

必需配置

配置项说明
TODOIST_API_TOKEN
Todoist API Token

获取 Token：

  1. 登录 Todoist → 设置 → 集成 → 开发者
  2. 或访问：https://app.todoist.com/app/settings/integrations/developer
  3. 复制 API Token

在 

.env
中配置：

TODOIST_API_TOKEN=your_todoist_api_token_here

工具依赖

工具用途说明
curl
HTTP API 调用系统通常自带
jq
JSON 解析Windows: 
choco install jq
; macOS: 
brew install jq

验证配置

curl -s "https://api.todoist.com/rest/v2/projects" \
  -H "Authorization: Bearer $TODOIST_API_TOKEN" | jq '.[0].name'

Instructions

Todoist API v2 基础

所有请求发送到 

https://api.todoist.com/rest/v2/
，携带 Bearer Token：

curl -s "https://api.todoist.com/rest/v2/{endpoint}" \
  -H "Authorization: Bearer $TODOIST_API_TOKEN" \
  -H "Content-Type: application/json"

核心概念

概念说明
Task（任务）待办事项，Todoist 的核心单元
Project（项目）任务的容器，类似文件夹
Section（分区）项目内的分组/栏目
Label（标签）跨项目的任务分类标签
Filter（过滤器）自定义查询条件
Priority（优先级）1=普通, 2=低, 3=中, 4=紧急（API 与 UI 相反）
Due Date（截止日期）支持自然语言和 ISO 8601

优先级映射

注意 API 的优先级数字与 Todoist UI 显示是相反的：

API 值UI 显示颜色
priority: 1
Priority 4（普通）无色
priority: 2
Priority 3（低）蓝色
priority: 3
Priority 2（中）橙色
priority: 4
Priority 1（紧急）红色

Workflows

Workflow 1: 任务 CRUD

创建任务

基本创建

curl -s -X POST "https://api.todoist.com/rest/v2/tasks" \
  -H "Authorization: Bearer $TODOIST_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "完成项目方案",
    "description": "包含技术选型和时间线",
    "due_string": "明天下午3点",
    "due_lang": "zh",
    "priority": 4,
    "project_id": "PROJECT_ID"
  }' | jq '.'

带标签和分区的创建

curl -s -X POST "https://api.todoist.com/rest/v2/tasks" \
  -H "Authorization: Bearer $TODOIST_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Review PR #42",
    "description": "Check error handling and test coverage",
    "due_date": "2025-03-05",
    "priority": 3,
    "project_id": "PROJECT_ID",
    "section_id": "SECTION_ID",
    "labels": ["code-review", "urgent"]
  }' | jq '.'

创建子任务

curl -s -X POST "https://api.todoist.com/rest/v2/tasks" \
  -H "Authorization: Bearer $TODOIST_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "编写单元测试",
    "parent_id": "PARENT_TASK_ID",
    "priority": 2
  }' | jq '.'

查看任务

获取所有活跃任务

curl -s "https://api.todoist.com/rest/v2/tasks" \
  -H "Authorization: Bearer $TODOIST_API_TOKEN" | jq '.'

按项目筛选

curl -s "https://api.todoist.com/rest/v2/tasks?project_id=PROJECT_ID" \
  -H "Authorization: Bearer $TODOIST_API_TOKEN" | jq '.'

按标签筛选

curl -s "https://api.todoist.com/rest/v2/tasks?label=urgent" \
  -H "Authorization: Bearer $TODOIST_API_TOKEN" | jq '.'

使用过滤器查询

curl -s "https://api.todoist.com/rest/v2/tasks?filter=today%20%7C%20overdue" \
  -H "Authorization: Bearer $TODOIST_API_TOKEN" | jq '.'

获取单个任务

curl -s "https://api.todoist.com/rest/v2/tasks/TASK_ID" \
  -H "Authorization: Bearer $TODOIST_API_TOKEN" | jq '.'

更新任务

curl -s -X POST "https://api.todoist.com/rest/v2/tasks/TASK_ID" \
  -H "Authorization: Bearer $TODOIST_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "更新后的任务标题",
    "due_string": "下周一",
    "due_lang": "zh",
    "priority": 3
  }' | jq '.'

完成任务

curl -s -X POST "https://api.todoist.com/rest/v2/tasks/TASK_ID/close" \
  -H "Authorization: Bearer $TODOIST_API_TOKEN"

重新打开任务

curl -s -X POST "https://api.todoist.com/rest/v2/tasks/TASK_ID/reopen" \
  -H "Authorization: Bearer $TODOIST_API_TOKEN"

删除任务

curl -s -X DELETE "https://api.todoist.com/rest/v2/tasks/TASK_ID" \
  -H "Authorization: Bearer $TODOIST_API_TOKEN"

Workflow 2: 项目管理

列出所有项目

curl -s "https://api.todoist.com/rest/v2/projects" \
  -H "Authorization: Bearer $TODOIST_API_TOKEN" | jq '.[] | {id, name, color, is_favorite}'

创建项目

curl -s -X POST "https://api.todoist.com/rest/v2/projects" \
  -H "Authorization: Bearer $TODOIST_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q2 产品开发",
    "color": "blue",
    "is_favorite": true,
    "view_style": "board"
  }' | jq '.'


view_style
可选：

  • list
    ：列表视图（默认）
  • board
    ：看板视图

更新项目

curl -s -X POST "https://api.todoist.com/rest/v2/projects/PROJECT_ID" \
  -H "Authorization: Bearer $TODOIST_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q2 产品开发（已完成）",
    "color": "grey"
  }' | jq '.'

删除项目

curl -s -X DELETE "https://api.todoist.com/rest/v2/projects/PROJECT_ID" \
  -H "Authorization: Bearer $TODOIST_API_TOKEN"

Workflow 3: 分区管理

分区（Section）用于在项目内组织任务，类似看板的列。

列出分区

curl -s "https://api.todoist.com/rest/v2/sections?project_id=PROJECT_ID" \
  -H "Authorization: Bearer $TODOIST_API_TOKEN" | jq '.'

创建分区

curl -s -X POST "https://api.todoist.com/rest/v2/sections" \
  -H "Authorization: Bearer $TODOIST_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "PROJECT_ID",
    "name": "进行中"
  }' | jq '.'

常见分区模板

看板式

for section in "待处理" "进行中" "待审核" "已完成"; do
  curl -s -X POST "https://api.todoist.com/rest/v2/sections" \
    -H "Authorization: Bearer $TODOIST_API_TOKEN" \
    -H "Content-Type: application/json" \
    -d "{\"project_id\": \"PROJECT_ID\", \"name\": \"$section\"}"
done

GTD 式

for section in "收集箱" "下一步行动" "等待中" "将来/也许" "参考资料"; do
  curl -s -X POST "https://api.todoist.com/rest/v2/sections" \
    -H "Authorization: Bearer $TODOIST_API_TOKEN" \
    -H "Content-Type: application/json" \
    -d "{\"project_id\": \"PROJECT_ID\", \"name\": \"$section\"}"
done

Workflow 4: 标签管理

列出所有标签

curl -s "https://api.todoist.com/rest/v2/labels" \
  -H "Authorization: Bearer $TODOIST_API_TOKEN" | jq '.[] | {id, name, color, is_favorite}'

创建标签

curl -s -X POST "https://api.todoist.com/rest/v2/labels" \
  -H "Authorization: Bearer $TODOIST_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "high-energy",
    "color": "red"
  }' | jq '.'

推荐标签体系

类别标签用途
精力
high-energy
, 
low-energy
按精力状态选择任务
时长
5min
, 
15min
, 
30min
, 
1hour
按可用时间选择任务
场景
at-computer
, 
at-phone
, 
at-office
, 
anywhere
按场景选择任务
类型
meeting
, 
deep-work
, 
admin
, 
learning
按任务性质分类

Workflow 5: 截止日期与重复任务

自然语言日期（推荐）

Todoist 支持多语言自然语言日期：

{
  "due_string": "明天下午3点",
  "due_lang": "zh"
}
中文表达英文等效解析结果
今天today当天
明天tomorrow次日
后天in 2 days两天后
下周一next Monday下个周一
每天every day每日重复
每周一every Monday每周一重复
每月1号every 1st每月1日重复
3月15日March 15指定日期

ISO 日期格式

{
  "due_date": "2025-03-15"
}

或带时间：

{
  "due_datetime": "2025-03-15T15:00:00Z"
}

重复任务

{
  "due_string": "every weekday at 9am",
  "due_lang": "en"
}

常见重复规则：

规则
due_string
说明
每日
every day
每天
工作日
every weekday
周一至周五
每周
every week
每 7 天
每月
every month
每月同日
每季度
every 3 months
每 3 个月
每年
every year
每年同日
完成后 3 天
every! 3 days
完成后 3 天再次出现
隔周一
every other Monday
每两周的周一

Workflow 6: 高级过滤查询

过滤器语法

过滤器说明
today
今天到期的任务
overdue
已过期任务
today | overdue
今天到期或已过期
7 days
未来 7 天到期
no date
没有截止日期的任务
p1
优先级 1（紧急）
p1 & today
紧急且今天到期
#项目名
指定项目的任务
@标签名
指定标签的任务
assigned to: me
分配给自己的任务
created before: -7 days
7 天前创建的任务

查询示例

今日待办

curl -s "https://api.todoist.com/rest/v2/tasks?filter=today%20%7C%20overdue" \
  -H "Authorization: Bearer $TODOIST_API_TOKEN" | \
  jq '.[] | {content, due: .due.string, priority}'

本周紧急任务

curl -s "https://api.todoist.com/rest/v2/tasks?filter=7%20days%20%26%20(p1%20%7C%20p2)" \
  -H "Authorization: Bearer $TODOIST_API_TOKEN" | \
  jq '.[] | {content, due: .due.string, priority}'

Workflow 7: 批量操作

从对话生成任务

当用户在对话中提到多个待办事项时，批量创建：

tasks='[
  {"content": "准备周会PPT", "due_string": "明天", "priority": 3},
  {"content": "回复客户邮件", "due_string": "今天", "priority": 4},
  {"content": "代码审查 PR #55", "due_string": "后天", "priority": 2}
]'

echo "$tasks" | jq -c '.[]' | while read task; do
  curl -s -X POST "https://api.todoist.com/rest/v2/tasks" \
    -H "Authorization: Bearer $TODOIST_API_TOKEN" \
    -H "Content-Type: application/json" \
    -d "$task" | jq '{id, content, url}'
  sleep 0.3
done

批量完成任务

task_ids=("TASK_ID_1" "TASK_ID_2" "TASK_ID_3")

for id in "${task_ids[@]}"; do
  curl -s -X POST "https://api.todoist.com/rest/v2/tasks/$id/close" \
    -H "Authorization: Bearer $TODOIST_API_TOKEN"
  sleep 0.3
done

任务导出

curl -s "https://api.todoist.com/rest/v2/tasks" \
  -H "Authorization: Bearer $TODOIST_API_TOKEN" | \
  jq -r '["内容","项目ID","优先级","截止日期","标签"], (.[] | [.content, .project_id, .priority, (.due.date // "无"), (.labels | join(","))]) | @csv' \
  > tasks_export.csv

Output Format

任务列表输出

📋 今日待办 (5 项)

🔴 [P1] 回复客户紧急邮件
   📅 今天 14:00 | 🏷️ work, urgent
   📁 客户项目

🟠 [P2] Review PR #42
   📅 今天 | 🏷️ code-review
   📁 开发任务

⚪ [P4] 整理会议纪要
   📅 今天 | 🏷️ admin
   📁 日常事务

✅ 已完成: 3 项 | ⏰ 逾期: 1 项

创建确认

✅ 任务已创建
- 内容: 完成项目方案
- 项目: Q2 产品开发
- 截止: 明天 15:00
- 优先级: P1 (紧急)
- 标签: deep-work
- 链接: https://todoist.com/app/task/12345

Common Pitfalls

1. API Token 无效

症状：所有请求返回 401 解决：确认 

TODOIST_API_TOKEN
正确设置，到 Todoist 设置页面重新获取

2. 优先级数字混淆

API 的 

priority: 4
对应 UI 的 P1（紧急），这是反直觉的。牢记映射关系或在代码中使用常量：

P1_URGENT=4
P2_HIGH=3
P3_MEDIUM=2
P4_NORMAL=1

3. 中文日期解析失败

使用中文自然语言日期时必须指定 

due_lang: "zh"
，否则会解析失败或解析为错误日期。

4. 过滤器 URL 编码

通过 curl 传递过滤器时需要 URL 编码：

  • |
    → 
    %7C
  • &
    → 
    %26
  • #
    → 
    %23
  • 空格 → 
    %20

5. 项目/任务 ID 是字符串

Todoist REST API v2 返回的 ID 是字符串类型，不是数字。使用 jq 处理时注意类型。

6. 批量操作超频

Todoist API 的限制是每分钟约 450 次请求。批量操作时添加 sleep：

sleep 0.3  # 每次请求间隔 300ms

7. 重复任务的 close vs delete

  • close
    （完成）：对重复任务，会自动创建下一次任务
  • delete
    ：永久删除，不会创建下次任务

确保对重复任务使用 

close
而非 
delete
。

8. 时区问题

带时间的截止日期使用 UTC 格式。如果用户在东八区（CST），需注意时差：

{
  "due_datetime": "2025-03-15T07:00:00Z"
}

上述表示北京时间 15:00。

进阶用法

每日回顾脚本

echo "=== 📋 每日回顾 $(date +%Y-%m-%d) ==="
echo ""
echo "--- 🔴 逾期任务 ---"
curl -s "https://api.todoist.com/rest/v2/tasks?filter=overdue" \
  -H "Authorization: Bearer $TODOIST_API_TOKEN" | \
  jq -r '.[] | "  ❗ \(.content) (原定: \(.due.date))"'
echo ""
echo "--- 📅 今日任务 ---"
curl -s "https://api.todoist.com/rest/v2/tasks?filter=today" \
  -H "Authorization: Bearer $TODOIST_API_TOKEN" | \
  jq -r '.[] | "  • [\(if .priority == 4 then "P1" elif .priority == 3 then "P2" elif .priority == 2 then "P3" else "P4" end)] \(.content)"'
echo ""
echo "--- 📆 明日预览 ---"
curl -s "https://api.todoist.com/rest/v2/tasks?filter=tomorrow" \
  -H "Authorization: Bearer $TODOIST_API_TOKEN" | \
  jq -r '.[] | "  ○ \(.content)"'

项目进度统计

PROJECT_ID="your_project_id"
total=$(curl -s "https://api.todoist.com/rest/v2/tasks?project_id=$PROJECT_ID" \
  -H "Authorization: Bearer $TODOIST_API_TOKEN" | jq 'length')
echo "📊 项目进度: 剩余 $total 个活跃任务"

EXTEND.md 扩展

用户可在技能同目录下创建 

EXTEND.md
添加：

  • 默认项目 ID 和名称映射
  • 自定义标签体系
  • 任务模板（如每周例行任务）
  • 与其他工具的集成配置
  • 团队成员 ID 映射