Todoist Orbit

使用捆绑的Python CLI。它在命令层是异步的，并且仅使用Python标准库的HTTP原语，因此无需安装SDK依赖。

先决条件

在环境中设置TODOISTAPIKEY。

首先找到已安装的技能路径

ClawHub将技能安装在OpenClaw技能目录下，例如~/.openclaw/skills/todoist-orbit/，但不要盲目假设确切路径。如有需要，请先验证安装位置，然后从该位置运行脚本。

bash
SKILL_DIR=$HOME/.openclaw/skills/todoist-orbit
[ -f $SKILLDIR/scripts/todoistorbit.py ] || echo 在运行命令前，请验证todoist-orbit的安装路径

主要命令

bash
python3 $SKILLDIR/scripts/todoistorbit.py --pretty ...

如果你是从检出仓库而非已安装的技能运行，请相应调整SKILL_DIR。

常用命令

任务

bash
python3 $SKILLDIR/scripts/todoistorbit.py --pretty tasks list --filter today
python3 $SKILLDIR/scripts/todoistorbit.py --pretty tasks add 发布版本 --project-id id> --section-id id> --due tomorrow --priority 1
python3 $SKILLDIR/scripts/todoistorbit.py --pretty tasks update --content 发布v2版本 --due next monday
python3 $SKILLDIR/scripts/todoistorbit.py --pretty tasks move id> --project-id id> --section-id
python3 $SKILLDIR/scripts/todoistorbit.py --pretty tasks close

保持tasks add ... content和--description简短。仅将它们用于任务标题和简要摘要。如果需要多行笔记、日志、检查清单、转录或结构化更新，请将这些内容放入评论中，而不是扩展任务字段。

项目

bash
python3 $SKILLDIR/scripts/todoistorbit.py --pretty projects list
python3 $SKILLDIR/scripts/todoistorbit.py --pretty projects search client
python3 $SKILLDIR/scripts/todoistorbit.py --pretty projects add 客户运营 --view-style board --favorite
python3 $SKILLDIR/scripts/todoistorbit.py --pretty projects archive

projects search现在调用Todoist服务端的GET /api/v1/projects/search端点。当需要在API搜索结果之上进行精确名称匹配时，请保留--exact。

分区

bash
python3 $SKILLDIR/scripts/todoistorbit.py --pretty sections list --project-id
python3 $SKILLDIR/scripts/todoistorbit.py --pretty sections add 收件箱
python3 $SKILLDIR/scripts/todoistorbit.py --pretty sections move id> id>

sections move为CLI兼容性而保留，但Todoist REST未提供分区移动端点，因此该命令会退出并显示记录的错误，而不是尝试移动。

标签

bash
python3 $SKILLDIR/scripts/todoistorbit.py --pretty labels list
python3 $SKILLDIR/scripts/todoistorbit.py --pretty labels search waiting
python3 $SKILLDIR/scripts/todoistorbit.py --pretty labels add waiting-for --color berry_red --favorite
python3 $SKILLDIR/scripts/todoistorbit.py --pretty labels update --name waiting-on --color blue
python3 $SKILLDIR/scripts/todoistorbit.py --pretty labels get
python3 $SKILLDIR/scripts/todoistorbit.py --pretty labels delete

labels search现在调用Todoist服务端的GET /api/v1/labels/search端点。当需要在API搜索结果之上进行精确名称匹配时，请保留--exact。

附件和评论

先上传文件，或让comments add隐式完成。

bash
python3 $SKILLDIR/scripts/todoistorbit.py --pretty uploads add ./voice-note.m4a
python3 $SKILLDIR/scripts/todoistorbit.py --pretty comments add --task-id 附上语音备忘录 --attachment ./voice-note.m4a
python3 $SKILLDIR/scripts/todoistorbit.py --pretty comments add-file --task-id ./daily-log.txt
python3 $SKILLDIR/scripts/todoistorbit.py --pretty comments add-stdin --task-id < 每日日志

• - 调查了API回归问题
• 部署了回滚
• 监控错误预算

Todoist将附件存储在评论上，而不是直接存储在任务对象上。对于任务附件，请使用--attachment添加任务评论。

格式和安全指南：

• - Todoist评论是纯文本。将Markdown渲染、缩进和粘贴的shell片段视为尽力而为，而非富文本格式。
• 对于超过短句长度的内容，优先使用comments add-file或comments add-stdin，而不是内联shell参数。
• 避免对评论正文进行shell插值。像comments add --task-id ... $NOTE这样的命令很脆弱，可能会引入意外字符，例如多余的前导$。
• 对已保存的笔记使用add-file，对here-docs或生成输出使用add-stdin。两种方式都能保留多行文本，无需shell引号技巧。

并发解析

bash
python3 $SKILLDIR/scripts/todoistorbit.py --pretty resolve --project 工作 --section 收件箱 --task-filter today

当需要一次调用完成项目和分区查找以及任务查询时，请使用resolve。

操作说明

• - 解析后优先使用ID；名称具有歧义性。
• CLI仅支持REST；没有同步API回退。
• projects search和labels search使用Todoist的GET /api/v1/projects/search和GET /api/v1/labels/search端点。--exact作为兼容性标志保留，用于将API结果缩小到精确名称匹配。
• sections move故意不支持，因为Todoist REST未暴露分区移动操作。该命令仅保留，以便为已调用它的调用者清晰报错。
• comments add --attachment上传文件，并将返回的附件对象传递给评论创建请求。
• 优先使用简短的任务字段和较长的评论：任务内容/描述在保持简洁时更易于浏览，而评论更适合运行日志和多行笔记。
• 仅在需要端点特定细节或附件行为时，阅读references/api-notes.md。