# 帮助中心

本页用于处理 TokST 安装、连接和日常使用中的常见问题。每个条目都提供最快处理路径和验证命令。

## 安装与更新

### `tokst: command not found`

安装独立 CLI 后，打开新的终端使 PATH 生效。

```sh
curl -fsSL https://tokst.com/install.sh | bash
tokst version
```

Windows PowerShell：

```powershell
irm https://tokst.com/install.ps1 | iex
tokst version
```

Windows Git Bash 支持 Unix 命令，安装脚本会自动启动 PowerShell 安装器。

### 更新后版本仍然较旧

`tokst update` 会升级启动当前命令的安装渠道：独立版下载校验后的二进制，npm 执行全局 npm 更新，Bun 执行全局 Bun 更新。使用版本详情检查当前渠道，独立版需要优先执行时修复终端 PATH。

```sh
tokst update
tokst version --verbose
tokst doctor
tokst doctor --fix-path
```

独立安装或 PATH 修复后请打开新的终端。安装器会保留 npm 和 Bun 安装，并记录独立二进制位置，同时保留云端授权。

## 登录与云端连接

### 浏览器授权没有返回终端

浏览器确认期间保持终端进程运行。浏览器显示连接请求失效时，重新开始授权流程。

```sh
tokst setup
tokst connection test
```

CI、服务器和无人值守环境使用 API 密钥：

```sh
tokst login --key tk_live_xxxx
tokst connection test
```

### `tokst doctor` 将知识库绑定显示为可选

知识库绑定用于目录级项目路由。账户、工作区、搜索和记忆都可以直接使用。目录长期属于某个项目时再建立绑定。

```sh
tokst atlas list
tokst atlas bind --atlas-id <atlas-id>
```

## 本地模式与 SQLite

### 在当前设备创建私有记忆

```sh
tokst setup --local
tokst local remember "私有笔记" --type note
tokst local search "私有"
```

本地记忆、附件、搜索索引和备份都保存在系统应用数据目录。备份与显式云端同步请参考 [TokST Local](/docs/local)。

### `CHECK constraint failed` 或 `SQL logic error`

更新到最新独立 CLI，创建备份后检查本地配置。

```sh
tokst update
tokst local backup create --name before-repair
tokst local status --json
```

提交问题时附上完整错误、`tokst version` 与 `tokst local status --json`。保留备份直到写入成功。

## 工作区与知识库

### 无法创建工作区或知识库

工作区和知识库创建遵循当前套餐额度。检查控制台中的账户用量，切换到目标工作区后重试。

```sh
tokst status
tokst workspace list
tokst atlas list
```

Cloud Free 包含一个个人工作区和一个知识库。团队工作区使用独立 Team 订阅和共享额度。详情参考 [版本与额度](/docs/editions)。

### 看不到团队邀请

受邀用户可以在控制台或 CLI 查看、接受或拒绝所有待处理邀请。

```sh
tokst workspace inbox
tokst workspace respond <invitation-id> --accept
```

团队 Owner 与 Admin 可在[团队协作](/docs/team-collaboration)中管理邀请。

## MCP 与智能体设置

### WorkBuddy、ZCode、Qoder 或 Kimi 无法打开浏览器授权

在“后台 → API 密钥”创建专用密钥。将客户端传输方式设为 Streamable HTTP，并通过 Authorization 请求头在每个请求中传递该密钥。停止使用客户端后请撤销该密钥。

```json
{
  "mcpServers": {
    "tokst": {
      "type": "streamable-http",
      "url": "https://api.tokst.com/mcp",
      "headers": {
        "Authorization": "Bearer tk_live_your_api_key"
      }
    }
  }
}
```

### MCP 工具没有出现

在运行本地 MCP 进程的同一台机器上完成授权，再重启 MCP 客户端。

```sh
tokst connection test
tokst init --agents codex,claude,cursor,opencode,pi --force
```

远端 MCP 重新连接 `https://api.tokst.com/mcp` 并完成 OAuth 授权。详情参考 [MCP 概述](/docs/mcp)。

### 智能体消息缺失

每个智能体读取自己的持久收件箱。长期运行的智能体可启动监听器获得即时投递，重启后通过收件箱同步消息。

```sh
TOKST_AGENT=1 tokst agent listen --json
TOKST_AGENT=1 tokst message inbox --json
```

使用 `tokst agent list` 查看当前智能体身份。[智能体身份](/docs/agent-identity)说明了权限、消息和在线状态。

## 文件、用量与安全

### 文件仍在，关联记忆已消失

打开控制台的“文件”页面并检查回收站。恢复记忆后将恢复常规关联；修复工具会识别待处理的孤立附件。

### 上传、用量或权限请求失败

确认目标工作区、个人或团队剩余额度以及工作区角色。Owner 管理订阅和审计权限，Admin 管理团队内容，Member 管理自己的记忆。

```sh
tokst status
tokst workspace list
```

API 密钥继承其所有者权限。请在控制台撤销闲置密钥，并仅向可信自动化提供密钥。详情参考 [API 密钥](/docs/api-keys)。

## 仍需协助

请准备命令、完整错误信息、已安装版本、操作系统，以及 Local、CLI、本地 MCP、远端 MCP、控制台或 REST API 的使用方式。完整信息可让支持和问题排查快速复现。

```sh
tokst version
tokst doctor
tokst connection test
tokst status --json
```