# 智能體設定

在一分鐘內為任何 AI 智能體配備 TokST 持久記憶。

## 瀏覽器設定（建議）

本機 CLI 或桌面智能體使用一條指令即可開始。安裝程式會下載獨立 TokST CLI，然後開啟瀏覽器授權：

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

Windows PowerShell 使用：

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

TokST 會開啟瀏覽器，確認已登入帳戶，並在本機儲存憑證後執行連接驗證。工作區與知識庫範圍繼續由每條指令、MCP 工具呼叫或可選的目錄綁定明確指定。

## 一鍵設定

複製以下訊息，貼上到智能體的對話框中：

```
請閱讀 https://tokst.com/skill.md 並按步驟安裝 TokST 記憶技能。
先執行：curl -fsSL https://tokst.com/install.sh | bash
```

智能體會讀取連結文件並完成對應的設定步驟：
1. 執行 `curl -fsSL https://tokst.com/install.sh | bash`
2. 完成瀏覽器授權
3. 在任意目錄執行 `tokst init --agents <agent>` 寫入智能體指令；需要專案路由時再另外建立並綁定知識庫
4. 支援 Skills 的用戶端將 `tokst-memory` 放入自己的 skills 目錄
5. 使用上下文與結構化 Markdown 開始記錄記憶

如果你的智能體無法直接存取連結，先下載文件：

```bash
curl -fsSL https://tokst.com/skill.md -o SKILL.md
```

然後告訴智能體：`閱讀 SKILL.md 並按步驟安裝。`

**內建版本檢查**——重新讀取該連結即可自動更新到最新版本。

> 技能檔案是無狀態的。所有記憶資料儲存在 TokST 雲端，不在這些檔案中。更新技能永遠不會影響你的資料。

---

## 支援哪些智能體？

將 `skill.md` 以 `SKILL.md` 的名稱放入目標智能體使用的目錄：

| 智能體 | 技能目錄 |
|--------|---------|
| Claude Code | `~/.claude/skills/tokst-memory/` |
| Codex | `~/.codex/skills/tokst-memory/` |
| Pi | `~/.pi/skills/tokst-memory/` |
| WorkBuddy | `~/.workbuddy/skills/tokst-memory/` |
| ZCode | `~/.zcode/skills/tokst-memory/` |
| Qoder | `~/.qoder/skills/tokst-memory/` |
| Kimi Code | `~/.kimi-code/skills/tokst-memory/` |
| Cursor / Windsurf | `~/.cursor/skills/tokst-memory/` |
| 任何相容 MCP 的智能體 | `~/.agents/skills/tokst-memory/` |

---

## 手動設定

全新電腦使用安裝腳本即可開始。它需要 Unix 終端和 `curl`；macOS、Linux 和 WSL 的標準環境均已提供。

```bash
# 安裝獨立 CLI，然後完成瀏覽器授權
curl -fsSL https://tokst.com/install.sh | bash
tokst doctor

# 驗證
tokst status
```

### 第 2 步：安裝技能檔案

最簡單的方式是使用上面的[一鍵設定](#一键设定推荐)——將訊息貼上到智能體對話框，它會自動完成安裝。

如需手動安裝，使用一鍵設定腳本而非逐個下載檔案：

### 第 3 步：新增 MCP（可選）

TokST 支援 Claude Code、Codex、Pi、WorkBuddy、ZCode、Qoder、Kimi 與其他 MCP 用戶端。支援 OAuth 的用戶端可直接連接雲端端點，用戶端會開啟 TokST 完成授權，無需本機執行環境。僅在遠端服務需要聚焦的 11 個核心記憶工具時設定 `TOKST_MCP_TOOLSET=core`：

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

WorkBuddy、ZCode、Qoder、Kimi 等使用靜態設定的用戶端可透過專用 API 金鑰連線。在[儀表板 API 金鑰](https://tokst.com/dashboard/api-keys)建立金鑰後，填入以下 Streamable HTTP 設定：

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

每個用戶端使用獨立金鑰；停止使用後可在儀表板撤銷對應金鑰。

需要本機程序的用戶端可在執行安裝腳本後繼續使用本機 stdio MCP。

---

## 儀表板捷徑

在[儀表板](https://tokst.com/dashboard/api-keys)建立 API 金鑰時，建立彈窗會顯示：
- 可直接複製的 **SKILL.md**（內嵌你的金鑰）
- **快速安裝腳本**（一鍵貼上到終端機）
- **MCP 設定** JSON
- 每個金鑰旁的 **Copy for Agent** 按鈕

你也可以直接分享 `https://tokst.com/skill.md`——智能體會自行處理其餘步驟。

---

## 驗證是否正常運作

```bash
# 檢查 CLI 連線
tokst status

# 檢查技能檔案已安裝（根據你的智能體調整路徑）
head -5 ~/.claude/skills/tokst-memory/SKILL.md
# 應顯示: --- name: tokst-memory ... version: 0.8.3 ---

# 儲存一筆測試記憶
TOKST_AGENT=1 tokst remember "智能體設定完成" --type note --json

# 搜尋它
TOKST_AGENT=1 tokst search "智能體設定" --json

# 選用：一次啟用自動記憶橋接器
tokst auto on --agent all
tokst acp proxy -- <acp-agent-command> [args]
tokst auto status
```

### OpenCode 終端、App 與 ACP

OpenCode 終端與 macOS App 重新啟動一次後會載入 TokST 全域外掛。`opencode` 建立的工作階段和 `opencode -s` 恢復的工作階段都會映射到同一個 TokST Session，並更新同一筆自動記憶。ACP 相容編輯器或 IDE 也可透過 TokST 啟動 OpenCode。

```bash
tokst auto on --agent opencode
tokst acp opencode --doctor
```

將以下智能體指令設定到 ACP 用戶端：

```json
{
  "command": "tokst",
  "args": ["acp", "opencode"]
}
```

`tokst auto repair --agent opencode` 會依目前 TokST 可執行檔絕對路徑重新產生全域外掛。`tokst acp opencode --repair` 保留 ACP Host 修復流程。

## 常見問題

| 問題 | 解決方法 |
|------|---------|
| 智能體看不到技能 | 確認技能目錄路徑與你的智能體匹配（`~/.claude/skills/`、`~/.cursor/skills/` 等）|
| `tokst: command not found` | 執行 `curl -fsSL https://tokst.com/install.sh \| bash`，然後開啟新的終端。 |
| `Not logged in` | `tokst login --key tk_live_xxxx` |
| MCP 工具不顯示 | 在與 MCP 伺服器相同的機器上執行 `tokst login` |
| 技能版本過舊 | 重新讀取 `tokst.com/skill.md` 或重新下載檔案 |
| 自動記憶未出現 | 執行 `tokst auto status --agent opencode` 或 `tokst auto status --agent workbuddy`；安裝橋接器後重新啟動對應用戶端。|
| `tokst acp opencode` 顯示舊設定 | 執行 `tokst acp opencode --repair`，然後重新啟動 ACP 用戶端。|
| 自動記憶攔截工作階段 | 執行 `tokst auto status`；金鑰、密碼、Cookie 和私鑰會在上傳前被主動移除或攔截。|

完整 CLI 參考：[CLI 指令](/docs/cli)