企业官网建设流程全解析

• AI Agent
• 知识库

长时运行的 Agent 工作流（如构建全栈应用、深度调研）对用户而言常常是"黑盒"：你只知道它在跑，却不知道它此刻在做什么、已完成哪些步骤、卡在了哪里。本指南以 awesome-openclaw-usecases 仓库中的 Todoist Task Manager 用例 为核心，讲解如何让 OpenClaw 通过三个 bash 脚本把内部推理过程与进度日志实时同步到 Todoist，从而获得一个可随时查看的 Agent 任务看板。读完本文，你将掌握 Todoist REST API 的封装方法、任务/评论的同步脚本实现，以及一套可直接复制使用的 Agent 提示词。

痛点：长时 Agent 任务的"黑盒"问题

当 Agent 执行复杂的多步骤任务（比如搭建一个全栈应用、完成一次深度研究）时，用户很难跟踪：

• Agent 当前正在做什么？
• 哪些步骤已经完成？
• Agent 是不是卡住了？

对于后台运行的任务，手动翻看聊天日志既繁琐又低效。这正是 todoist-task-manager.md 要解决的问题——把 Agent 的运行状态"外置"到用户每天都打开的任务管理工具中。

方案概述：What It Does

该用例借助todoist-task-manager技能（skill）实现四项能力：

1. 可视化状态：在 Todoist 项目中按特定分区（section）创建任务，例如🟡 In Progress（进行中）、🟠 Waiting（等待中）。
2. 外化推理：将 Agent 内部的"Plan"（计划）写入任务描述（description）。
3. 流式日志：将每个子步骤的完成情况以评论（comment）形式实时追加到任务下。
4. 自动对账：通过一个心跳（heartbeat）脚本检查停滞任务，并及时通知用户。

该用例在仓库 README.md 的 Productivity（生产力）分类中被描述为："通过将推理和进度日志同步到 Todoist，最大化智能体的透明度"。

前置条件：你甚至不需要预装技能

一个关键的设计理念是：你不需要预先安装任何现成技能。只需要给 OpenClaw Agent 一段提示词，让它自己创建下文配置指南中描述的 bash 脚本。因为 OpenClaw 能够管理自己的文件系统并执行 shell 命令，它会在收到请求后"现场搭建"这套技能。

仓库维护者在 README.md 中同时给出了重要安全提醒：OpenClaw 技能和第三方依赖可能存在严重安全漏洞，社区技能多未经过维护者审计，务必审查技能源码、检查请求的权限，并避免硬编码 API 密钥或凭据。下文会给出相应的安全实践建议。

详细配置指南

1. 配置 Todoist 侧

首先在 Todoist 中完成准备工作：

1. 创建一个项目（Project），例如命名为 "OpenClaw Workspace"，并获取其Project ID。
2. 在该项目中为不同状态创建分区（Section）：
   • 🟡 In Progress（进行中）
   • 🟠 Waiting（等待中）
   • 🟢 Done（已完成）
3. 获取每个分区的Section ID，以及你的Todoist API Token。

这些 ID 将在后续脚本中作为占位符被替换。你既可以在 Todoist 网页端手动创建分区，也可以让 Agent 通过 Todoist REST API 的sections端点完成创建——从脚本结构可以推断，这套系统的核心就是围绕tasks、comments、sections等 REST v2 端点展开的。

2. 实现："Agent 自建"的技能脚本

这套"技能"由三个脚本组成，每个脚本负责与 Todoist API 通信的不同部分。原文档提供了完整代码，下面逐一展开讲解。

scripts/todoist_api.sh——核心 API 封装

这是整个系统的底层封装，负责所有与 Todoist REST API 的 HTTP 通信。用法为./todoist_api.sh <endpoint> <method> [data_json]：

#!/bin/bash # Usage: ./todoist_api.sh <endpoint> <method> [data_json] ENDPOINT=$1 METHOD=$2 DATA=$3 TOKEN="YOUR_TODOIST_API_TOKEN" if [ -z "$DATA" ]; then curl -s -X "$METHOD" "https://api.todoist.com/rest/v2/$ENDPOINT" \ -H "Authorization: Bearer $TOKEN" else curl -s -X "$METHOD" "https://api.todoist.com/rest/v2/$ENDPOINT" \ -H "Authorization: Bearer $TOKEN" \ -H "Content-Type: application/json" \ -d "$DATA" fi

要点说明：

• 端点拼接：所有请求统一发往https://api.todoist.com/rest/v2/下的相对端点，例如tasks、tasks/{id}、comments。
• 认证方式：通过Authorization: Bearer请求头携带 API Token。
• 有无请求体的分支：当第三个参数（数据 JSON）为空时，仅发送带认证头的请求；否则额外附带Content-Type: application/json与-d数据体。这使其同时支持 GET 类查询与 POST 类写入。
• 安全建议：原文档以硬编码变量TOKEN="YOUR_TODOIST_API_TOKEN"示意，但依据仓库 README.md 的安全警告，强烈建议改为从环境变量读取（如TOKEN="${TODOIST_TOKEN}"），避免将密钥写入脚本文件。

scripts/sync_task.sh——任务与状态管理

负责创建任务或更新任务状态。用法为./sync_task.sh <task_content> <status> [task_id] [description] [labels_json_array]：

#!/bin/bash # Usage: ./sync_task.sh <task_content> <status> [task_id] [description] [labels_json_array] CONTENT=$1 STATUS=$2 TASK_ID=$3 DESCRIPTION=$4 LABELS=$5 PROJECT_ID="YOUR_PROJECT_ID" case $STATUS in "In Progress") SECTION_ID="SECTION_ID_PROGRESS" ;; "Waiting") SECTION_ID="SECTION_ID_WAITING" ;; "Done") SECTION_ID="SECTION_ID_DONE" ;; *) SECTION_ID="" ;; esac PAYLOAD="{\"content\": \"$CONTENT\"" [ -n "$SECTION_ID" ] && PAYLOAD="$PAYLOAD, \"section_id\": \"$SECTION_ID\"" [ -n "$PROJECT_ID" ] && [ -z "$TASK_ID" ] && PAYLOAD="$PAYLOAD, \"project_id\": \"$PROJECT_ID\"" if [ -n "$DESCRIPTION" ]; then ESC_DESC=$(echo "$DESCRIPTION" | sed ':a;N;$!ba;s/\n/\\n/g' | sed 's/"/\\"/g') PAYLOAD="$PAYLOAD, \"description\": \"$ESC_DESC\"" fi [ -n "$LABELS" ] && PAYLOAD="$PAYLOAD, \"labels\": $LABELS" PAYLOAD="$PAYLOAD}" if [ -n "$TASK_ID" ]; then ./scripts/todoist_api.sh "tasks/$TASK_ID" POST "$PAYLOAD" else ./scripts/todoist_api.sh "tasks" POST "$PAYLOAD" fi

要点说明：

• 状态到分区的映射：通过case语句把语义化的状态（In Progress/Waiting/Done）映射到具体的section_id，实现"任务出现在哪个分区"的控制。
• 任务创建与更新的分支：传入task_id时更新已有任务（POST 到tasks/{id}），否则创建新任务（POST 到tasks）。注意更新时不再携带project_id——这是从脚本第 68 行[ -n "$PROJECT_ID" ] && [ -z "$TASK_ID" ]的条件中可以推断的行为，避免对已存在任务误改项目归属。
• 描述转义：使用sed把描述中的换行符转为\n、双引号转义为\"，确保多行 Plan 能作为合法 JSON 字符串提交。
• 标签支持：第五个参数labels_json_array会以 JSON 数组原样拼入 payload，可用于给任务打上类型标签。

scripts/add_comment.sh——进度日志记录

负责把子步骤完成日志实时追加到任务评论中。用法为./add_comment.sh <task_id> <comment_text>：

#!/bin/bash # Usage: ./add_comment.sh <task_id> <comment_text> TASK_ID=$1 TEXT=$2 ESC_TEXT=$(echo "$TEXT" | sed ':a;N;$!ba;s/\n/\\n/g' | sed 's/"/\\"/g') PAYLOAD="{\"task_id\": \"$TASK_ID\", \"content\": \"$ESC_TEXT\"}" ./scripts/todoist_api.sh "comments" POST "$PAYLOAD"

要点说明：

• 评论即日志：Todoist 的comments端点允许向任务追加评论，这里被复用为"进度日志流"——每完成一个子步骤就追加一条评论，用户在 Todoist 任务详情页即可看到按时间排列的执行记录。
• 同样的转义逻辑：与sync_task.sh一致，对换行与双引号做 JSON 转义，保证多行日志安全提交。

3. 使用提示词：同时完成"搭建"与"使用"

原文档提供了一个可直接复制给 Agent 的提示词，它既指导 Agent 完成脚本搭建，也定义了后续每个复杂任务的处理流程：

I want you to build a Todoist-based task visibility system for your own runs. First, create three bash scripts in a 'scripts/' folder: 1. todoist_api.sh (a curl wrapper for Todoist REST API) 2. sync_task.sh (to create or update tasks with specific section_ids for In Progress, Waiting, and Done) 3. add_comment.sh (to post progress logs as comments) Use these variables for the setup: - Token: [Your Todoist API Token] - Project ID: [Your Project ID] - Section IDs: [In Progress ID, Waiting ID, Done ID] Once created, for every complex task I give you: 1. Create a task in 'In Progress' with your full PLAN in the description. 2. For every sub-step completion, call add_comment.sh with a log of what you did. 3. Move the task to 'Done' when finished.

这段提示词的核心是定义了"任务生命周期协议"：

1. 接到复杂任务 → 在In Progress分区创建任务，把完整计划（PLAN）写入描述；
2. 每个子步骤完成 → 调用add_comment.sh记录一条日志；
3. 全部完成 → 把任务移到Done分区（即用sync_task.sh更新section_id）。

运行原理与源码级解读

一次典型运行的调用链

从三个脚本的调用关系可以还原出完整链路：

sync_task.sh "构建登录页" "In Progress" "" "Plan: 1.设计UI 2.写后端..." └─ todoist_api.sh "tasks" POST "{...section_id...}" → 创建任务，返回 task_id add_comment.sh <task_id> "已完成：UI 骨架搭建" └─ todoist_api.sh "comments" POST "{...}" → 追加进度日志 sync_task.sh "构建登录页" "Done" <task_id> └─ todoist_api.sh "tasks/<task_id>" POST "{...section_id:Done...}" → 收尾

也就是说，todoist_api.sh是唯一直接接触网络的层，sync_task.sh与add_comment.sh在其上构建语义操作，Agent 则只需按提示词约定调用高层脚本即可。这种分层设计让 API Token 只出现在一处，便于集中管理与替换。

心跳对账：停滞任务检测

原文档在能力清单中提到一个心跳（heartbeat）脚本：定期检查是否存在长时间没有新评论、也没有移动到Done的任务（即"停滞任务"），并通知用户。该脚本不在本次提供的三个脚本之列，从文档描述可以推断，其实现思路是：调用tasks端点按section_id拉取In Progress/Waiting分区下的任务，结合评论的最后更新时间判断活跃度，超时则触发通知（例如发送到 Telegram 或邮件）。这保证了即使 Agent 卡死，用户也能第一时间被提醒，而不会让任务无声地悬在那里。

与其他用例的组合使用

仓库中有多个用例与 Todoist 相关，这套可视化系统可以与它们形成闭环：

• Automated Meeting Notes & Action Items：该用例会把会议纪要中的行动项自动创建到 Jira、Linear、Todoist 或 Notion。原文档明确建议："将此用例与 Todoist Task Manager 搭配使用，以获得 Agent 创建任务的完整可见性"——会议行动项由 Agent 自动创建后，同样可以通过本系统被追踪与展示。
• Multi-Channel Personal Assistant：该用例把 Todoist 作为"快速任务捕获"渠道，用户在任何对话中说"把 [任务] 加入我的待办"即触发 Todoist 写入；与本系统结合后，这些由 Agent 写入的任务也能以同样方式获得状态可视化。

安全注意事项

基于仓库 README.md 的明确警告，在使用本方案时请注意：

• 不要硬编码 API Token：原文档脚本中TOKEN="YOUR_TODOIST_API_TOKEN"仅为示意。实际使用时请通过环境变量注入，或使用 OpenClaw 的密钥管理机制，避免密钥随脚本文件泄露。
• 审查脚本来源：本方案的核心卖点是"让 Agent 现场自建脚本"，因此在首次运行前，请人工检查 Agent 生成的脚本内容，确认其只调用预期的端点、只读取预期的变量。
• 最小权限原则：Todoist API Token 只应具备本项目所需的最小范围，并妥善保管。

相关资源

• 本方案对应的原文档：usecases/todoist-task-manager.md
• 仓库总览与完整用例索引：README.md
• 贡献指南（如何新增用例）：CONTRIBUTING.md
• 官方参考：Todoist REST API v2 文档可在 Todoist 开发者门户查阅，本方案用到的关键端点包括tasks（创建/更新任务）、tasks/{id}（按 ID 更新）、comments（追加评论）以及用于获取分区 ID 的sections端点。

小结

Todoist Task Manager 用例的巧妙之处在于：它没有引入任何新的"技能安装"负担，而是把 Todoist 这样一个用户本就高频使用的工具，变成 Agent 的"状态显示器"。通过三个 bash 脚本，OpenClaw 就能在 Todoist 中实时呈现自己的计划、进度与停滞状态，让长时任务的透明度从"翻聊天记录"升级为"看一眼任务看板"。配合心跳对账机制与仓库中其他 Todoist 相关用例，它可以进一步融入你的日常工作流，成为 Agent 自治运行的可信仪表盘。

• AI Agent
• 知识库