Mind Key 与 JWT — 何时用哪个？

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

快速决策表

简单规则

Mind Key — 数据访问令牌

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

• LLM Agent 跨会话持久化记忆
• 后台 Cron 任务
• MCP Server 配置
• Webhook 集成
• 移动应用读取记忆

Mind Key 能做什么

• GET /memory/recall — 读取该 Mind 中的所有记忆
• POST /memory — 存储/更新记忆
• GET /chat/poll — 读取聊天消息
• POST /chat/reply — 发送聊天消息
• GET /mind/tasks — 列出任务
• POST /mind/task — 创建任务
• POST /script — 存储脚本
• POST /webhooks — 注册 Webhook
• POST /computers/:id/commands — 排队计算机命令

Mind Key 不能做什么

• 创建/列出/删除 Mind（需 JWT）
• 与其他用户共享 Mind（需 JWT）
• 查看用户账户信息（需 JWT）
• 订阅 Web Push（需 JWT）

JWT — 账户管理令牌

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

JWT 能做什么

• POST /minds — 创建新 Mind（返回新 Mind Key）
• GET /minds — 列出该用户的所有 Mind
• DELETE /minds/:id — 删除 Mind
• POST /sharing — 与其他用户共享 Mind
• POST /push/subscribe — 订阅 Web Push 通知
• GET /sharing — 列出 Mind 共享

JWT 不能做什么

• 读写记忆（需 Mind Key）
• 发送聊天消息（需 Mind Key）
• 管理任务（需 Mind Key）
• 注册 Webhook（需 Mind Key）

特殊情况：Computer Token

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

常见模式

模式 1：单个 LLM Agent

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

模式 2：多项目 Agent

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

模式 3：团队共享

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

模式 4：MCP Server

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

令牌格式速查

下一步

• Authentication — 完整认证指南
• User 与 Minds API — 由 JWT 保护的端点
• Memory API — 由 Mind Key 保护的端点