{"title":"Mind Key 与 JWT — 何时用哪个？","slug":"mind-key-vs-jwt","category":"getting-started","summary":"决策指南：Agent 数据访问用 Mind Key，账户管理用 JWT。","audience":["human","llm"],"tags":["auth","mind-key","jwt","decision-guide"],"difficulty":"beginner","updated":"2026-06-27","word_count":439,"read_minutes":2,"llm_context":"Mind Key: tenant-scoped, never expires, for memory/chat/tasks/scripts/computers/webhooks.\nJWT: user-scoped, 7-day expiry, for /register, /login, /minds (CRUD), /sharing, /push.\nSimple rule: if it touches a single mind's data → Mind Key. If it manages the account → JWT.\nException: /computers/me/* uses Computer Token (not Mind Key or JWT).\n","lang":"zh","translated":true,"requested_lang":"zh","content_markdown":"\n# Mind Key 与 JWT — 何时用哪个？\n\nSynapse 有两种认证令牌。选错会导致 401 错误。本指南给你一个清晰的决策框架。\n\n## 快速决策表\n\n| 你想... | 使用 |\n|----------------|-----|\n| 存储/回放记忆 | Mind Key |\n| 发送/轮询聊天消息 | Mind Key |\n| 管理任务 | Mind Key |\n| 存储脚本 | Mind Key |\n| 注册 Webhook | Mind Key |\n| 控制计算机 | Mind Key（用户侧）/ Computer Token（Agent 侧） |\n| 注册用户账户 | 无（公共） |\n| 登录 | 无（公共） |\n| 创建/列出/删除 Mind | JWT |\n| 与其他用户共享 Mind | JWT |\n| 订阅 Web Push 通知 | JWT |\n| 查看审计日志 | Mind Key |\n\n## 简单规则\n\n> [!TIP]\n> **如果涉及单个 Mind 的数据 → Mind Key。**\n> **如果管理账户或 Mind 元数据 → JWT。**\n\n## Mind Key — 数据访问令牌\n\nMind Key 授予访问**一个 Mind 的数据**的权限。它是永不过期（除非删除该 Mind）的长生命周期令牌。非常适合：\n\n- LLM Agent 跨会话持久化记忆\n- 后台 Cron 任务\n- MCP Server 配置\n- Webhook 集成\n- 移动应用读取记忆\n\n### Mind Key 能做什么\n\n- `GET /memory/recall` — 读取该 Mind 中的所有记忆\n- `POST /memory` — 存储/更新记忆\n- `GET /chat/poll` — 读取聊天消息\n- `POST /chat/reply` — 发送聊天消息\n- `GET /mind/tasks` — 列出任务\n- `POST /mind/task` — 创建任务\n- `POST /script` — 存储脚本\n- `POST /webhooks` — 注册 Webhook\n- `POST /computers/:id/commands` — 排队计算机命令\n\n### Mind Key 不能做什么\n\n- 创建/列出/删除 Mind（需 JWT）\n- 与其他用户共享 Mind（需 JWT）\n- 查看用户账户信息（需 JWT）\n- 订阅 Web Push（需 JWT）\n\n## JWT — 账户管理令牌\n\nJWT 对**用户账户**进行认证。它在 7 天后过期，用于跨多个 Mind 或涉及其他用户的账户级操作。\n\n### JWT 能做什么\n\n- `POST /minds` — 创建新 Mind（返回新 Mind Key）\n- `GET /minds` — 列出该用户的所有 Mind\n- `DELETE /minds/:id` — 删除 Mind\n- `POST /sharing` — 与其他用户共享 Mind\n- `POST /push/subscribe` — 订阅 Web Push 通知\n- `GET /sharing` — 列出 Mind 共享\n\n### JWT 不能做什么\n\n- 读写记忆（需 Mind Key）\n- 发送聊天消息（需 Mind Key）\n- 管理任务（需 Mind Key）\n- 注册 Webhook（需 Mind Key）\n\n## 特殊情况：Computer Token\n\n`/computers/me/*` 端点（Agent 侧，供 screen-remote-agent 使用）使用第三种令牌类型：**Computer Token**。该令牌由 `POST /computers/register` 在兑换安装码时返回，专属于某一台已注册的计算机。\n\n| 端点 | 认证 |\n|----------|------|\n| `GET /computers/me/poll` | Computer Token |\n| `POST /computers/me/commands/:cid/result` | Computer Token |\n| `GET /computers/list` | Mind Key 或 JWT |\n| `POST /computers/:id/commands` | Mind Key 或 JWT |\n\n## 常见模式\n\n### 模式 1：单个 LLM Agent\n\n1. 注册一次 → 获取 JWT\n2. 创建一个 Mind → 获取 Mind Key\n3. LLM 用 Mind Key 完成所有操作\n\n### 模式 2：多项目 Agent\n\n1. 注册一次 → 获取 JWT\n2. 创建多个 Mind（work、personal、project-x） → 获取多个 Mind Key\n3. LLM 根据上下文加载不同 Mind Key\n\n### 模式 3：团队共享\n\n1. 用户 A 创建 Mind → 获取 Mind Key A\n2. 用户 A 通过 JWT 共享给用户 B（`POST /sharing`）\n3. 用户 B 现在可通过自己的 JWT 访问\n4. 对于 LLM 访问，用户 B 需创建自己的 Mind Key（或使用 A 的）\n\n### 模式 4：MCP Server\n\nMCP Server 始终使用 Mind Key（通过 `SYNAPSE_MIND_KEY` 环境变量设置）。一个 MCP Server 实例 = 一个 Mind。如需访问多个 Mind，请运行多个 MCP 实例或在客户端实现 Mind 切换。\n\n## 令牌格式速查\n\n| 令牌 | 格式 | 示例 |\n|-------|--------|---------|\n| Mind Key | `mk_` + 36 字符 | `mk_aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789` |\n| JWT | `eyJ` + base64 | `eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...` |\n| Computer Token | `ct_` + 36 字符 | `ct_xYzAbCdEfGhIjKlMnOpQrStUvWxYz0123456789` |\n\n## 下一步\n\n- [Authentication](/docs/getting-started/authentication) — 完整认证指南\n- [User 与 Minds API](/docs/api/user) — 由 JWT 保护的端点\n- [Memory API](/docs/api/memory) — 由 Mind Key 保护的端点\n","content_html":"

Mind Key 与 JWT — 何时用哪个？

\n

Synapse 有两种认证令牌。选错会导致 401 错误。本指南给你一个清晰的决策框架。

\n

快速决策表

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
你想...使用
存储/回放记忆Mind Key
发送/轮询聊天消息Mind Key
管理任务Mind Key
存储脚本Mind Key
注册 WebhookMind Key
控制计算机Mind Key（用户侧）/ Computer Token（Agent 侧）
注册用户账户无（公共）
登录无（公共）
创建/列出/删除 MindJWT
与其他用户共享 MindJWT
订阅 Web Push 通知JWT
查看审计日志Mind Key
\n

简单规则

\n
**如果涉及单个 Mind 的数据 → Mind Key。**\n**如果管理账户或 Mind 元数据 → JWT。**

Mind Key — 数据访问令牌

\n

Mind Key 授予访问一个 Mind 的数据的权限。它是永不过期（除非删除该 Mind）的长生命周期令牌。非常适合：

\n\n

Mind Key 能做什么

\n\n

Mind Key 不能做什么

\n\n

JWT — 账户管理令牌

\n

JWT 对用户账户进行认证。它在 7 天后过期，用于跨多个 Mind 或涉及其他用户的账户级操作。

\n

JWT 能做什么

\n\n

JWT 不能做什么

\n\n

特殊情况：Computer Token

\n

/computers/me/* 端点（Agent 侧，供 screen-remote-agent 使用）使用第三种令牌类型：Computer Token。该令牌由 POST /computers/register 在兑换安装码时返回，专属于某一台已注册的计算机。

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
端点认证
GET /computers/me/pollComputer Token
POST /computers/me/commands/:cid/resultComputer Token
GET /computers/listMind Key 或 JWT
POST /computers/:id/commandsMind Key 或 JWT
\n

常见模式

\n

模式 1：单个 LLM Agent

\n
    \n
  1. 注册一次 → 获取 JWT
    2. \n
  2. 创建一个 Mind → 获取 Mind Key
    3. \n
  3. LLM 用 Mind Key 完成所有操作
    4. \n
\n

模式 2：多项目 Agent

\n
    \n
  1. 注册一次 → 获取 JWT
    2. \n
  2. 创建多个 Mind（work、personal、project-x） → 获取多个 Mind Key
    3. \n
  3. LLM 根据上下文加载不同 Mind Key
    4. \n
\n

模式 3：团队共享

\n
    \n
  1. 用户 A 创建 Mind → 获取 Mind Key A
    2. \n
  2. 用户 A 通过 JWT 共享给用户 B（POST /sharing）
    3. \n
  3. 用户 B 现在可通过自己的 JWT 访问
    4. \n
  4. 对于 LLM 访问，用户 B 需创建自己的 Mind Key（或使用 A 的）
    5. \n
\n

模式 4：MCP Server

\n

MCP Server 始终使用 Mind Key（通过 SYNAPSE_MIND_KEY 环境变量设置）。一个 MCP Server 实例 = 一个 Mind。如需访问多个 Mind，请运行多个 MCP 实例或在客户端实现 Mind 切换。

\n

令牌格式速查

\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n
令牌格式示例
Mind Keymk_ + 36 字符mk_aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789
JWTeyJ + base64eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...
Computer Tokenct_ + 36 字符ct_xYzAbCdEfGhIjKlMnOpQrStUvWxYz0123456789
\n

下一步

\n\n","urls":{"html":"/docs/getting-started/mind-key-vs-jwt","text":"/docs/getting-started/mind-key-vs-jwt?format=text","json":"/docs/getting-started/mind-key-vs-jwt?format=json","llm":"/docs/getting-started/mind-key-vs-jwt?format=llm"},"translations_available":["en","zh","hi","es","fr","ar","pt","ru","ja","de","it","ko","nl","pl","tr","sv","vi","th","id","uk"]}