# Mind Key 与 JWT — 何时用哪个？

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

## 快速决策表

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

## 简单规则

> [!TIP]
> **如果涉及单个 Mind 的数据 → Mind Key。**
> **如果管理账户或 Mind 元数据 → JWT。**

## 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` 在兑换安装码时返回，专属于某一台已注册的计算机。

| 端点 | 认证 |
|----------|------|
| `GET /computers/me/poll` | Computer Token |
| `POST /computers/me/commands/:cid/result` | Computer Token |
| `GET /computers/list` | Mind Key 或 JWT |
| `POST /computers/:id/commands` | Mind Key 或 JWT |

## 常见模式

### 模式 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 切换。

## 令牌格式速查

| 令牌 | 格式 | 示例 |
|-------|--------|---------|
| Mind Key | `mk_` + 36 字符 | `mk_aBcDeFgHiJkLmNoPqRsTuVwXyZ0123456789` |
| JWT | `eyJ` + base64 | `eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...` |
| Computer Token | `ct_` + 36 字符 | `ct_xYzAbCdEfGhIjKlMnOpQrStUvWxYz0123456789` |

## 下一步

- [Authentication](/docs/getting-started/authentication) — 完整认证指南
- [User 与 Minds API](/docs/api/user) — 由 JWT 保护的端点
- [Memory API](/docs/api/memory) — 由 Mind Key 保护的端点