---
name: tokenstack-setup
description: 配置 TokenStack (www.tokenstack.cc) API 中转站。支持 OpenClaw（龙虾）、Claude Code、Cursor、Windsurf 等客户端的一键配置。帮助用户设置 API Key、Base URL 和模型。
argument-hint: [客户端名称]
disable-model-invocation: true
allowed-tools: Bash(cat *) Bash(cp *) Bash(mkdir *) Read Edit Write AskUserQuestion
---

# TokenStack 中转站配置助手

你正在帮助用户配置 **TokenStack** (www.tokenstack.cc) API 中转站。

## TokenStack API 端点信息

TokenStack 支持三个系列的 API：

| 系列 | Base URL | API 类型 |
|------|----------|----------|
| **Claude** (Anthropic) | `https://www.tokenstack.cc` | `anthropic-messages` |
| **OpenAI** (GPT 等) | `https://www.tokenstack.cc/v1` | `openai-completions` |
| **Google** (Gemini / 生图) | `https://www.tokenstack.cc/v1` | `google-generative-ai` |

## 配置流程

### 第一步：确认客户端

如果用户通过 `$ARGUMENTS` 指定了客户端，直接跳到第二步。否则，用 AskUserQuestion 询问用户要配置哪个客户端：

- **OpenClaw（龙虾）** — 个人 AI 助手
- **Claude Code** — Anthropic 官方 CLI
- **Cursor** — AI 编程 IDE
- **Windsurf** — AI 编程 IDE

### 第二步：一次性收集关键信息（三个问题）

用 **一次** AskUserQuestion 同时问以下三个问题：

**问题 1 — 要配置哪个客户端？**（单选，如果第一步已确认则跳过此问题）
- OpenClaw（龙虾） — 个人 AI 助手
- Claude Code — Anthropic 官方 CLI
- Cursor — AI 编程 IDE
- Windsurf — AI 编程 IDE

**问题 2 — 需要接入哪些模型？**（多选）
- Claude 系列 — claude-sonnet-4-6, claude-opus-4-6 等
- OpenAI 系列 — gpt-5.5, gpt-5.4, gpt-5.3-codex 等
- Google 系列 — gemini-3.1-flash-image-time 等

**无论用户选择预设模型还是自填模型，都必须提醒**：请到 www.tokenstack.cc 复制完整的模型名称，模型名不能有任何拼写错误，否则会导致请求失败。

**问题 3 — TokenStack API Key**（单选）
- 直接输入 Key — 选"其他"粘贴你的 sk-xxx
- 已设置环境变量 TOKENSTACK_API_KEY — 跳过输入，直接引用环境变量
- 还没有 Key — 引导用户前往 www.tokenstack.cc 注册账号，然后在后台创建对应模型系列的令牌（Token）

### 第三步：自动检测配置文件

通过 Bash/Read 工具自动检测对应客户端的配置文件是否存在：
- OpenClaw: `~/.openclaw/openclaw.json`
- Claude Code: `~/.zshrc` 或 `~/.bashrc`
- Cursor: `~/Library/Application Support/Cursor/User/settings.json`
- Windsurf: `~/Library/Application Support/Windsurf/User/settings.json`

如果存在，告知用户会在现有配置基础上合并；如果不存在，告知用户会创建新配置。

### 第四步：备份原配置文件

**写入任何配置之前，必须先备份原文件。** 这一步不可跳过。

对检测到的已有配置文件，执行备份：
```bash
cp <原配置文件> <原配置文件>.bak.$(date +%Y%m%d%H%M%S)
```

示例：
- `cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.bak.20260421103000`
- `cp ~/.zshrc ~/.zshrc.bak.20260421103000`

备份完成后告知用户备份路径，以便出问题时可以恢复。

### 第五步：生成并写入配置

根据用户选择的客户端，按照下方对应的配置指南完成配置。

### 第六步：验证配置

配置完成后：

1. 展示写入的配置内容供用户确认
2. 如果是 OpenClaw，提示用户运行 `openclaw models status --probe` 验证
3. 如果是 Claude Code，提示用户运行一个简单的测试命令
4. 告诉用户如何切换模型或修改配置

## 注意事项

- **安全**：绝不将 API Key 明文写入配置文件，始终使用环境变量
- **备份**：修改配置文件前，必须先备份原文件
- **验证**：写入前确认路径和内容正确
- 如果用户的配置文件已存在，应该合并而不是覆盖

---

## 客户端配置指南

### OpenClaw（龙虾）

**配置文件**：`~/.openclaw/openclaw.json`（JSON5 格式）

#### 1. 设置环境变量

在 `~/.openclaw/.env` 或系统环境变量中添加：

```bash
TOKENSTACK_API_KEY=sk-你的密钥
```

#### 2. 配置 Provider

根据用户选择的模型系列，在 `models.providers` 中添加对应的 provider。

**Claude 系列：**

```json5
{
  models: {
    mode: "merge",
    providers: {
      tokenstack: {
        baseUrl: "https://www.tokenstack.cc",
        apiKey: "${TOKENSTACK_API_KEY}",
        api: "anthropic-messages",
        models: [
          { id: "claude-sonnet-4-6", name: "Claude Sonnet 4.6" },
          { id: "claude-opus-4-6", name: "Claude Opus 4.6" },
          { id: "claude-haiku-4-5-20251001", name: "Claude Haiku 4.5" },
        ],
      },
    },
  },
}
```

**OpenAI 系列：**

```json5
{
  models: {
    mode: "merge",
    providers: {
      "tokenstack-openai": {
        baseUrl: "https://www.tokenstack.cc/v1",
        apiKey: "${TOKENSTACK_API_KEY}",
        api: "openai-completions",
        models: [
          { id: "gpt-5.5", name: "GPT 5.5" },
          { id: "gpt-5.4", name: "GPT 5.4" },
          { id: "gpt-5.3-codex", name: "GPT 5.3 Codex" },
        ],
      },
    },
  },
}
```

**Google 系列：**

```json5
{
  models: {
    mode: "merge",
    providers: {
      "tokenstack-google": {
        baseUrl: "https://www.tokenstack.cc/v1",
        apiKey: "${TOKENSTACK_API_KEY}",
        api: "google-generative-ai",
        models: [
          { id: "gemini-3.1-flash-image-time", name: "Gemini 3.1 Flash Image Time" },
        ],
      },
    },
  },
}
```

#### 3. 设置默认模型

```json5
{
  agents: {
    defaults: {
      model: {
        primary: "tokenstack/claude-sonnet-4-6",  // 或用户选择的模型
        fallbacks: ["tokenstack-openai/gpt-5.4"],   // 可选回退
      },
      models: {
        "tokenstack/claude-sonnet-4-6": { alias: "Sonnet" },
        "tokenstack/claude-opus-4-6": { alias: "Opus" },
        "tokenstack-openai/gpt-5.4": { alias: "GPT" },
        "tokenstack-google/gemini-3.1-flash-image-time": { alias: "Gemini" },
      },
    },
  },
}
```

#### 4. 合并配置

**重要**：如果用户已有 `openclaw.json`，需要合并配置而非覆盖。

操作步骤：
1. 读取现有配置文件
2. 在 `models.providers` 中添加 tokenstack 相关 provider
3. 在 `agents.defaults.models` 中添加模型别名
4. 更新 `agents.defaults.model.primary`（如用户同意）

#### 5. 验证

完成后提示用户运行：

```bash
openclaw models status --probe
openclaw models list
```

---

### Claude Code

**配置方式**：通过环境变量配置。

#### 1. 设置环境变量

在 shell 配置文件（`~/.zshrc` / `~/.bashrc`）中添加：

```bash
export ANTHROPIC_BASE_URL="https://www.tokenstack.cc"
export ANTHROPIC_API_KEY="sk-你的密钥"
```

或者在项目根目录创建 `.env` 文件：

```bash
ANTHROPIC_BASE_URL=https://www.tokenstack.cc
ANTHROPIC_API_KEY=sk-你的密钥
```

#### 2. 操作步骤

1. 确认要写入的位置（shell 配置 or .env 文件）
2. 如果写入 shell 配置文件：
   - 读取 `~/.zshrc`（macOS）或 `~/.bashrc`（Linux）
   - 检查是否已有 `ANTHROPIC_BASE_URL` 和 `ANTHROPIC_API_KEY`
   - 如果已有，提示用户是否覆盖
   - 追加或替换环境变量
   - 提示用户执行 `source ~/.zshrc` 使其生效
3. 如果写入 .env 文件：
   - 确认项目目录
   - 写入 .env 并提醒添加到 .gitignore

#### 3. 验证

```bash
source ~/.zshrc
echo $ANTHROPIC_BASE_URL
# 应输出: https://www.tokenstack.cc
```

**注意**：Claude Code 使用 Anthropic Messages API 格式，base URL 是 `https://www.tokenstack.cc`（不带 `/v1`）。

---

### Cursor

**配置方式**：通过 IDE 设置界面或配置文件。

#### 1. 通过设置界面配置（推荐）

1. 打开 Cursor → Settings（`Cmd + ,`）
2. 搜索 "API" 或 "Model"
3. 根据模型系列配置：

**Claude 系列：**
- Override API Base: `https://www.tokenstack.cc`
- API Key: 输入 TokenStack API Key

**OpenAI 系列：**
- Override OpenAI API Base: `https://www.tokenstack.cc/v1`
- OpenAI API Key: 输入 TokenStack API Key

#### 2. 通过配置文件配置

配置文件位于：
- macOS: `~/Library/Application Support/Cursor/User/settings.json`
- Linux: `~/.config/Cursor/User/settings.json`
- Windows: `%APPDATA%\Cursor\User\settings.json`

```json
{
  "cursor.aiProvider.apiBase": "https://www.tokenstack.cc/v1",
  "cursor.aiProvider.apiKey": "sk-你的密钥"
}
```

**注意**：Cursor 的配置项名称可能因版本更新而变化，优先引导用户通过设置界面配置。

---

### Windsurf

**配置方式**：通过 IDE 设置界面或配置文件。

#### 1. 通过设置界面配置（推荐）

1. 打开 Windsurf → Settings（`Cmd + ,`）
2. 搜索 "API" 或 "Provider"
3. 根据模型系列配置：

**Claude 系列：**
- API Base URL: `https://www.tokenstack.cc`
- API Key: 输入 TokenStack API Key

**OpenAI 系列：**
- API Base URL: `https://www.tokenstack.cc/v1`
- API Key: 输入 TokenStack API Key

#### 2. 通过配置文件配置

配置文件位于：
- macOS: `~/Library/Application Support/Windsurf/User/settings.json`
- Linux: `~/.config/Windsurf/User/settings.json`
- Windows: `%APPDATA%\Windsurf\User\settings.json`

**注意**：Windsurf 的配置项名称可能因版本更新而变化，优先引导用户通过设置界面配置。