> For AI agents: the complete documentation index is available at https://www.notionhub.app/llms.txt, the full documentation bundle is available at https://www.notionhub.app/llms-full.txt.

# Toggl 同步到 Notion 使用指南

## 功能介绍

NotionHub 可以将 Toggl Track 中的时间记录同步到 Notion，帮助你把每天花在不同项目、客户和任务上的时间自动沉淀到 Notion 中，方便做周复盘、月度总结、项目工时统计和个人时间分析。

Toggl 适合快速记录当下正在做什么，Notion 适合长期整理、筛选、归档和复盘。通过 NotionHub 同步后，你可以在 Notion 中统一查看自己的时间账本。

当前支持：

- 同步 Toggl 时间记录到 Notion。
- 同步时间记录的标题、开始时间、结束时间。
- 同步 Toggl 项目、客户和标签。
- 自动创建或关联 Notion 中的项目、客户、标签页面。
- 自动维护年、月、周、日和全部等时间维度关系。
- 支持首次导入历史记录。
- 支持日常增量同步，补充最新时间记录。
- 支持历史缺口补齐，减少中断同步导致的数据遗漏。
- 支持 Toggl 删除记录后，在 Notion 中归档对应页面。
- 支持从 Notion 反向创建时间记录到 Toggl，需要手动勾选。

只支持使用 NotionHub 提供的 Toggl Notion 模板。同步依赖模板中的数据库和字段结构，请不要删除数据库，也不要随意修改关键字段名称和字段类型。

## 预览效果

同步完成后，Notion 模板中会包含 Toggl 时间记录、项目、客户、标签和时间维度页面。

常见使用方式包括：

- 在时间记录库中查看每天做了什么。
- 按项目统计不同工作的投入时间。
- 按客户查看服务或合作项目的工时。
- 按标签区分工作、学习、生活、运动等不同类型。
- 按年、月、周、日查看时间分布。
- 在 Notion 中做周报、月报或年度复盘。

如果你已经在 Toggl 中长期记录时间，首次同步可能会导入较多历史数据，需要等待一段时间。

## 使用前准备

开始前请先确认：

- 已安装 NotionHub 浏览器插件。安装教程：[https://www.notionhub.app/docs/install.html](https://www.notionhub.app/docs/install.html)
- 已获取 Toggl 同步服务激活码。
- 已有 Toggl Track 账号。
- 已在 Toggl 中生成 API Token。
- 已复制 NotionHub 提供的 Toggl Notion 模板。
- 已完成 Notion 授权，并授权到复制出来的模板页面。

## 第一步：打开 Toggl 同步

打开 NotionHub 插件，在服务列表中选择「Toggl」。

第一次使用时，需要按顺序完成：

1. 激活服务。
2. 复制 Notion 模板。
3. 授权 Notion。
4. 填写 Toggl API Token。
5. 开始同步。

如果插件中没有看到 Toggl 服务，请先确认插件已经升级到支持 Toggl 同步的版本。

## 第二步：输入激活码

在「激活服务」步骤中输入 Toggl 同步服务的激活码，然后点击激活。

激活成功后，插件会进入 Notion 模板复制和授权步骤。

激活码只用于绑定当前同步服务，请不要把激活码分享给其他人。

## 第三步：复制模板并授权 Notion

点击插件中的「复制 Notion 模板」按钮，按照页面提示复制 NotionHub 提供的 Toggl 模板。

复制完成后，回到插件中继续完成 Notion 授权。

授权时需要注意：

- 只支持使用 NotionHub 提供的 Toggl 模板。
- 不要自己新建空页面替代模板。
- 不要删除模板中的数据库。
- 不要修改关键字段名称和字段类型。
- 模板复制完成后，可以移动到其他 Notion 页面下面整理。

只移动模板页面的位置不会影响同步。同步依赖的是模板中的数据库 ID 和 Notion 授权，不依赖模板位于侧边栏的哪个位置。

## 第四步：获取 Toggl API Token

Toggl 同步需要使用你的 Toggl API Token 读取时间记录。

获取方式：

1. 打开 Toggl Track：[https://track.toggl.com/](https://track.toggl.com/)
2. 登录你的 Toggl 账号。
3. 进入个人资料页面，也就是 Profile / My Profile。
4. 在页面底部找到 API Token。
5. 复制 API Token。
6. 回到 NotionHub 插件中粘贴保存。

请注意：

- API Token 相当于你的 Toggl 授权凭证，请不要公开分享。
- 如果怀疑 Token 泄露，可以在 Toggl 个人资料页面重置 API Token。
- 重置后，NotionHub 中也需要重新填写新的 API Token。

## 第五步：开始同步

完成激活、模板复制、Notion 授权和 Toggl API Token 填写后，点击「开始同步」。

首次同步会读取 Toggl 历史时间记录。历史数据较多时，同步时间会比较长，请耐心等待。

后续再次同步时，NotionHub 会优先同步最近新增或变更的记录，并自动补齐可能存在的历史缺口。

同步过程中请不要重复点击开始同步。如果插件提示任务正在运行，说明上一次同步还没有结束，等待任务完成后再查看 Notion 数据。

## 第六步：查看 Notion 数据

同步完成后，打开复制出来的 Notion 模板，可以看到：

- 时间记录：保存每一条 Toggl time entry。
- 项目：保存 Toggl 项目信息。
- 客户：保存 Toggl 客户信息。
- 标签：保存 Toggl 标签信息。
- 年、月、周、日：用于按时间维度整理记录。
- 全部：用于汇总全部时间数据。

时间记录中常见字段包括：

- 标题：Toggl 记录的描述；如果没有描述，会优先显示项目名。
- 时间：记录的开始时间和结束时间。
- Id：Toggl 时间记录 ID，用于去重，请不要手动修改。
- Project / 项目：对应 Toggl 项目。
- Client / 客户：对应 Toggl 客户。
- 标签：对应 Toggl 标签。
- 备注：Toggl 记录描述。
- 同步到 Toggl：用于 Notion 反向同步到 Toggl。

## 同步规则说明

### 1. 首次同步

如果 Notion 模板中还没有 Toggl 记录，NotionHub 会从 Toggl 账号创建时间开始导入历史记录。

如果你的 Toggl 账号使用时间很长，首次同步可能会比较慢。这是正常情况。

### 2. 日常增量同步

日常同步会优先处理最新记录，默认会回看最近一段时间，避免漏掉最近修改、跨天记录或接口延迟返回的数据。

### 3. 历史缺口补齐

如果 Notion 中间存在较长时间没有同步到的空档，NotionHub 会尝试自动补齐历史缺口。

这适合处理之前同步中断、接口失败或早期脚本漏同步造成的数据缺失。

### 4. 删除同步

如果你在 Toggl 中删除了一条时间记录，后续同步时 NotionHub 会在 Notion 中归档对应页面。

注意：

- 是归档，不是永久删除。
- 只处理从 Toggl 同步过来的记录。
- 手动在 Notion 创建、且没有 Toggl Id 的记录不会被自动归档。

### 5. Notion 反向同步到 Toggl

如果你想在 Notion 中新建一条时间记录，并同步回 Toggl，需要满足：

- 这条 Notion 记录的 `Id` 为空。
- 勾选 `同步到 Toggl`。
- 填写必要的标题和时间。

同步成功后，NotionHub 会把 Toggl 返回的 Id 写回 Notion，避免下次重复创建。

建议先从 Toggl 正向同步一次，让项目、客户等基础数据先进入 Notion，再使用反向同步功能。

## 常见问题

### 为什么首次同步很慢？

首次同步可能需要读取 Toggl 的全部历史时间记录。如果账号使用多年，数据量较大，同步时间会变长。

请等待任务完成，不要重复点击同步。

### 为什么 90 天以前的数据也能同步？

Toggl 的近期时间记录和历史报表数据使用不同接口。NotionHub 会根据时间范围自动选择合适的接口读取数据，因此可以尽量补齐更早的历史记录。

但历史数据接口可能受到 Toggl 套餐、权限或限流影响。如果历史数据无法完整读取，可以联系技术支持排查。

### 为什么同步失败提示 403？

常见原因包括：

- Toggl API Token 填写错误。
- API Token 已被重置。
- 当前 Toggl 用户没有对应 workspace 的访问权限。
- Toggl 接口拒绝当前请求。

可以重新复制 API Token 并在插件中更新后再次同步。

### 为什么同步失败提示 429？

429 通常表示 Toggl 接口限流。可以稍后再试。

如果历史数据特别多，首次同步更容易遇到限流，等待一段时间后重新触发同步即可。

### 为什么 Toggl 中有数据，但 Notion 没有显示？

可以按下面顺序检查：

1. Toggl API Token 是否正确。
2. Toggl 中是否确实有对应时间范围的记录。
3. Notion 模板是否使用官方模板。
4. 是否修改或删除过模板字段。
5. 同步任务是否仍在运行中。
6. 是否遇到 Toggl 接口限流或权限问题。

如果仍然异常，可以联系技术支持，并提供激活码和问题时间范围。

### 可以修改 Notion 模板字段吗？

不建议修改关键字段。

尤其不要修改或删除：

- 标题
- 时间
- Id
- Project / 项目
- Client / 客户
- 标签
- 同步到 Toggl
- 年、月、周、日、全部等关系字段

如果只是调整视图、排序、筛选、页面位置，一般不会影响同步。

### 可以移动模板页面吗？

可以。

你可以把复制出来的 Toggl 模板移动到自己的 Notion 工作区其他页面下面。只要没有删除数据库、没有移除 NotionHub 授权，就不会影响同步。

### 可以用自己的 Notion 模板吗？

不支持。

Toggl 同步依赖 NotionHub 模板中的数据库、字段和关系结构。使用自己的模板可能导致字段缺失、类型不匹配或关系无法写入。

### 删除 Toggl 记录后，Notion 会发生什么？

同步时，NotionHub 会把对应的 Notion 页面归档。

这样做是为了避免误删数据。如果你需要彻底删除，可以在 Notion 中手动删除已归档页面。

## 使用建议

如果你想更好地利用 Toggl + Notion，可以这样使用：

- 在 Toggl 中保持快速记录，不必过度整理。
- 用 Project 区分工作项目或生活事项。
- 用 Client 区分客户、公司、课程或长期目标。
- 用 Tags 标记深度工作、会议、学习、运动、娱乐等类型。
- 每周在 Notion 中按项目和标签复盘时间分布。
- 每月查看哪些事情占用了最多时间，调整下个月计划。

Toggl 负责记录当下，Notion 负责复盘长期趋势。同步之后，你会拥有一份可持续积累的个人时间数据库。

## 相关链接

- 插件安装文档：[https://www.notionhub.app/docs/install.html](https://www.notionhub.app/docs/install.html)
- Toggl 同步使用文档：[https://www.notionhub.app/docs/toggl.html](https://www.notionhub.app/docs/toggl.html)
- 技术支持：[https://www.notionhub.app/docs/support.html](https://www.notionhub.app/docs/support.html)
