# 幫助中心

本頁協助處理 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
```