# 启玥科技 · API 接入教程

整理日期：2026-10-05

控制台：https://token-api.qiyue999.com

## 01 · 从收货到第一次调用

本教程用于配置启玥科技 API 接入服务。你需要一台可安装目标工具的电脑、已购买的站内额度，以及控制台提供的接入参数。先完成一条短消息测试，再运行长任务。

1. **核对发货类型。**收到账号和密码：直接登录后改密；收到兑换码：先注册自己的账号，再到钱包兑换；已收到 API Key：仍需核对该 Key 的计费分组和有效额度。
2. **打开控制台。**使用 https://token-api.qiyue999.com 。接口根地址请再与发货信息核对，控制台域名与 API 域名可能不同。
3. **核对到账。**查看余额或订阅页，记录额度、有效期、激活状态；不要把试用、余额和订阅混为一谈。
4. **选择计费分组。**在 API 密钥 / 令牌管理页查看分组及其模型权限，选择按次或按量所对应的 Key。
5. **配置工具。**填入 Base URL、API Key、Model ID，保存并新建对话，发送“只回复 OK”。
6. **确认成功。**工具有返回，且站内日志出现对应模型、请求时间和扣费记录，才说明调用走到了目标站点。

兑换码用于充值，登录密码用于登录，API Key 用于模型调用。三者不能互相替代。

## 02 · 账户、兑换与续费

### 收到的是现成账号

1. 登录控制台，打开「个人资料 / 个人设置」。
2. 将用户名、密码改为自己常用的信息；绑定自己的邮箱，以便接收通知和找回账号。
3. 查看「钱包 / 订阅」与「API 密钥」：试用账号可能已带预设套餐和两种计费 Key。
4. 激活时间以页面显示为准。原素材分别提到首次登录、首次调用等方式，不要仅凭登录推定开始计时。

### 收到的是兑换码

1. 注册并登录自己的账号。
2. 打开「钱包管理 / 钱包」→「额度充值」，找到「兑换码充值」。
3. 粘贴兑换码，点击「兑换额度」。确认余额增加，再进入密钥管理。
4. 兑换码通常只能使用一次。显示已使用时，先查余额和充值记录，避免在多个账号间重复尝试。

钱包管理 → 额度充值 → 输入兑换码 → 核对到账

### 续费与账户维护

老用户将新兑换码兑换到原账户，有效 Key 通常可继续使用，无需反复更换。站内在线充值入口是否启用，以控制台显示为准；也可按商家提供的购买渠道补充额度。

余额档不主动兑换成限时订阅时，按商品规格永久有效。订阅另有有效期、配额和激活规则。删除账户前先完成账单导出和售后处理；删除后的资料能否恢复以系统确认页为准。

## 03 · 创建密钥与选择计费分组

1. 打开「API 密钥」或「令牌管理」，点击「添加令牌」。
2. 给 Key 起一个便于识别的名称，例如 `workbuddy-personal`。
3. 选择购买方案对应的分组。你提供的新版后台截图中，「按次计费」对应按次密钥，`default` 对应按量密钥。不同账户的可选分组可能不同。
4. 根据需要设置额度与到期日。Key 上显示“无限制”仅指 Key 本身未单独限额，不代表账户有无限余额。
5. 初次配置时不必随意限制模型；如果开启模型限制，需要把目标模型加入允许列表。
6. 保存并复制 Key，在工具里粘贴。对外分享截图时，遮住整段密钥、兑换码和密码。

workbuddy-request`sk-••••••••`按次计费

workbuddy-default`sk-••••••••`default / 按量

重绘示意图 · 分组以当前账户为准

如果发现密钥泄露，先停用旧 Key，再创建新 Key 并更新工具配置。给多个工具分别创建 Key，更容易区分消耗和排查问题。

## 04 · 三个参数与接口路径

| 参数 | 在哪里获取 | 常见错误 |
| --- | --- | --- |
| Base URL | 发货信息 / 控制台接入说明 | 把登录页、价格页或完整请求路径填入 |
| API Key | 密钥 / 令牌管理 | 填了兑换码、漏字符或复制了空格 |
| Model ID | 控制台当前模型列表 | 填写展示名，大小写或连字符不一致 |

### 什么时候加 /v1？

OpenAI 兼容 SDK 的 Base URL 通常使用「接口根地址 + /v1」；完整聊天请求路径一般为 `/v1/chat/completions`。Codex 需要 Responses 协议，通常为 `/v1/responses`。Anthropic SDK / Claude Code 通常填写根地址，由客户端拼接 `/v1/messages`。

部分客户端会自动添加 `/v1`，另一些要求填写完整地址。以所用工具的字段说明为准，避免出现 `/v1/v1`。控制台如果给出特殊路径，应优先使用控制台说明。

一个地址支持 Chat Completions，不代表它必然支持 Responses、Messages、图像生成或视频接口。先确认购买的通道与工具协议匹配。

### 可填写的配置示例

下方生成器仅在浏览器内拼接配置，不发送调用请求，也不要求你填写真实密钥。生成后把示例密钥换成自己的 Key。

## 05 · WorkBuddy 接入

1. 安装并登录你自己的 WorkBuddy，打开设置中的「模型 / 模型供应商 / 自定义模型」入口，名称随版本变化。
2. 添加支持的自定义供应商，选择 **OpenAI Compatible / OpenAI 兼容** 协议。如果只有官方积分入口，先确认版本是否开放自定义模型。
3. 填写接口地址、API Key 和准确的 Model ID。Base URL 是否自动追加 `/v1`，以输入框说明为准。
4. 保存并启用该模型，回到对话或项目中，明确选择刚添加的自定义模型。
5. 发一条短消息测试；再查看启玥控制台日志，确认模型与扣费分组。
6. 做编程或 Agent 任务前，确认模型支持工具调用。图片输入、长上下文等能力需单独确认。

此方式使用站内 API 额度，不会增加 WorkBuddy 官方积分；不要在软件充值页寻找兑换入口。自定义模型菜单不可见时，查看软件当前版本的帮助说明。

## 06 · CC Switch 管理多个工具

CC Switch 用于管理 Claude Code、Codex 等工具的配置，不替代目标工具本身的安装。

1. 从 [CC Switch 官方仓库发布页](https://github.com/farion1231/cc-switch/releases)下载适合 Windows / macOS / Linux 的安装包。
2. 先在顶部选择要管理的应用：Claude、Codex 或当前版本支持的其他应用。
3. 新建供应商，命名为「启玥科技」，填写该应用需要的地址、密钥和模型。
4. Claude 类工具使用 Messages 通道；Codex 使用 Responses 通道。不要只更改名称而沿用另一协议的参数。
5. 保存后启用该供应商。备份已有配置，避免覆盖其他工作环境。
6. 正常退出并重新打开目标工具，新建会话测试。如窗口关闭后配置仍旧，先保存任务，再确认后台应用已退出。

如果控制台令牌菜单提供 CC Switch 一键导入，可使用该入口；没有此入口时手动新增供应商即可。导入后仍需检查模型、地址与计费分组。

## 07 · Codex CLI 接入

以下给出自定义供应商的最小配置示例。需要目标通道支持 OpenAI Responses API；仅支持聊天接口的通道不能直接用于 Codex。

### 安装与准备

1. 从 [Node.js 官网](https://nodejs.org/)安装适合系统的 LTS 版本；开发项目建议安装 [Git](https://git-scm.com/)。
2. 新开终端，检查 Node.js 与 npm，然后安装 Codex CLI。

```
node --version
npm --version
npm install -g @openai/codex
codex --version
```

### 创建自定义供应商

Windows 配置路径通常是 `%USERPROFILE%\.codex\config.toml`；macOS / Linux 为 `~/.codex/config.toml`。先备份已有文件，再合并下方配置，避免同名配置重复。模型 ID 替换为控制台的 Codex 可用模型。

```
model_provider = "qiyue"
model = "YOUR_CODEX_MODEL_ID"

[model_providers.qiyue]
name = "Qiyue API"
base_url = "https://YOUR_API_HOST/v1"
env_key = "QIYUE_API_KEY"
wire_api = "responses"
```

### 在当前终端设置密钥

Windows PowerShell：

```
$env:QIYUE_API_KEY = "YOUR_API_KEY"
codex
```

macOS / Linux：

```
export QIYUE_API_KEY="YOUR_API_KEY"
codex
```

上述环境变量只在当前终端会话生效。进入自己的测试项目目录后启动，先用一个简短问题验证；不要直接在不熟悉的项目中运行会修改大量文件的任务。

### 桌面应用与 CLI 的区别

桌面应用从官方入口安装，具体登录和自定义供应商支持以当前应用版本说明为准。不要假定“通过终端设置的临时变量”会自动被从桌面图标启动的应用继承；需要按应用文档或 CC Switch 对应模式配置。

参考：[Codex 配置参考](https://developers.openai.com/codex/config-reference)、[高级配置](https://developers.openai.com/codex/config-advanced)。本次访问官方页面返回 403，以上为基于现有素材整理的最小示例，未进行真实密钥调用验证；请核对当前客户端版本。

## 08 · Claude Code 接入

1. 按 [Claude Code 安装说明](https://code.claude.com/docs/en/setup)完成安装，并在终端确认 `claude --version` 能返回版本。
2. 确认 Key 所在分组允许 Claude Code，并支持 Anthropic Messages 协议。
3. 在同一个终端内设置接口根地址和 API Key，再启动 Claude Code。

Windows PowerShell：

```
$env:ANTHROPIC_BASE_URL = "https://YOUR_API_HOST"
$env:ANTHROPIC_API_KEY = "YOUR_API_KEY"
claude --model "YOUR_CLAUDE_MODEL_ID"
```

macOS / Linux：

```
export ANTHROPIC_BASE_URL="https://YOUR_API_HOST"
export ANTHROPIC_API_KEY="YOUR_API_KEY"
claude --model "YOUR_CLAUDE_MODEL_ID"
```

这里通常不追加 `/v1`。确保地址、认证方式与网关说明一致；某些网关使用其他令牌字段，不要同时保留相互冲突的旧配置。只有设置地址而没有网关凭证，可能仍会沿用已有登录身份。

测试后检查站内日志。一次操作可能包含标题、上下文管理、工具调用等多次请求；看到多条扣费记录时，应核对每条的时间、模型和内容，而非只按一次鼠标点击计算。

## 09 · OpenCode 接入

1. 从 [OpenCode 官方文档](https://opencode.ai/docs/)按系统安装。
2. 在项目目录创建或合并 `opencode.json`，添加自定义 provider。
3. 模型键名必须与控制台 Model ID 完全一致；显示名可以自定义。
4. 在启动 OpenCode 的同一终端设置 `QIYUE_API_KEY`。也可按工具文档使用 `/connect` 管理凭证，provider ID 应与配置一致。
5. 启动后使用 `/models` 选择 `qiyue` 供应商对应的模型，再发送短消息验证。

```
{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "qiyue": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "启玥科技",
      "options": {
        "baseURL": "https://YOUR_API_HOST/v1",
        "apiKey": "{env:QIYUE_API_KEY}"
      },
      "models": {
        "YOUR_MODEL_ID": { "name": "我的模型" }
      }
    }
  },
  "model": "qiyue/YOUR_MODEL_ID"
}
```

本示例选择 OpenAI 兼容聊天协议。如果购买的是其他协议通道，应选择对应适配器。模型的工具调用、图片输入与上下文长度按实际能力设置。

## 10 · Cline / Kilo 与编辑器插件

### Cline

1. 在 VS Code 扩展市场安装 Cline，打开其侧栏设置。
2. API Provider 选择 **OpenAI Compatible**。
3. 填入 Base URL、API Key、Model ID；不要误选 OpenAI 官方供应商后仍把 Key 发往官方地址。
4. 按实际模型配置上下文长度、输出限制、图片和工具能力。不要填一个模型本身不支持的上限。
5. 如果 Plan / Act 使用独立模型，两个模式都需要检查供应商和密钥。
6. 点击验证或发起短任务，并在控制台确认日志。

### Kilo 等插件

找到供应商设置中的 OpenAI 兼容入口，填写同样三项参数。配置字段与多模式开关随版本变化，参照该插件当前文档。Cursor、Trae 等工具并非所有功能都允许用第三方 Key 替换官方服务，应先确认具体功能和账户权限。

## 11 · Cherry Studio / 聊天客户端

1. 在客户端「设置 → 模型服务」中新增供应商；类型选择 OpenAI 兼容。
2. 填入 API 地址和 Key，保存后启用供应商。
3. 点击获取模型列表；获取失败但已知准确 Model ID 时，可按工具支持方式手动添加。
4. 新建助手或对话，选择该供应商下的模型，不要继续使用旧的默认模型。
5. 发送短消息，检查响应和控制台记录。

部分客户端在地址后带特殊字符时会改变自动路径拼接规则。以当前输入框说明为准，不盲目沿用别人的完整 URL。聊天界面显示成功后，再逐项测试附件、图片、联网与工具调用。

## 12 · ZCode / 其他 Agent 通用接入

适用于提供自定义模型入口的 ZCode、OpenClaw 等工具。是否支持第三方模型、支持哪种协议，由工具自身决定。

1. 在目标工具的模型或供应商页面选择「自定义 / OpenAI 兼容」。
2. 复制发货信息中的地址、Key 和 Model ID，核对路径是否由工具自动补全。
3. 如果有模型映射，将工具预设模型映射到实际可用 ID。
4. 仅开启模型和通道已支持的功能，例如工具调用、图片输入或流式。
5. 从一个短对话逐步测试到简单任务，再运行复杂 Agent。不要一开始就大量并发。

如果工具没有自定义接口入口，或者被锁定在官方服务，就不能仅靠购买 Key 接入。先咨询工具官方文档或本店，再选购。

## 13 · 开发者最小请求示例

### Python / OpenAI 兼容聊天

安装 `pip install openai`，在当前终端设置 `QIYUE_API_KEY`，将地址与模型改成自己的配置。

```
import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["QIYUE_API_KEY"],
    base_url="https://YOUR_API_HOST/v1",
)
response = client.chat.completions.create(
    model="YOUR_MODEL_ID",
    messages=[{"role": "user", "content": "只回复 OK"}],
)
print(response.choices[0].message.content)
```

### Python / Anthropic Messages

安装 `pip install anthropic`，使用支持 Messages 的通道。

```
import os
from anthropic import Anthropic

client = Anthropic(
    api_key=os.environ["QIYUE_API_KEY"],
    base_url="https://YOUR_API_HOST",
)
response = client.messages.create(
    model="YOUR_CLAUDE_MODEL_ID",
    max_tokens=128,
    messages=[{"role": "user", "content": "只回复 OK"}],
)
for block in response.content:
    if block.type == "text":
        print(block.text)
```

这些代码是配置示例，未使用你的密钥进行实际调用。生产使用时先从服务器端验证，再增加流式、超时和重试处理。浏览器直连若遇 CORS，应通过你自己的服务端调用，不要把生产 Key 写入公开网页。

## 14 · 图像与视频模型

1. 在控制台确认当前可用模型及能力，区分文本、图片理解、图片生成、视频生成。
2. 查看模型的计费单位：按张、按秒、按次或 Token，以及分辨率、时长等附加费用。
3. 选择支持对应模型协议的客户端。图片生成常有独立接口；视频通常要先提交任务，再查询任务状态。
4. 先用最小尺寸、最短时长等低成本参数验证。参数合法值以当前模型文档为准。
5. 保存任务 ID，并在日志核对扣费和完成状态。

不要把旧素材中的“所有图片视频统一一折”“某时长固定几元”作为当前报价。部分模型临时下线、失败返还与任务保留时间，需看当前通道说明。

## 15 · 按顺序排查常见错误

地址 → Key → 余额 / 分组 → 模型 / 协议 → 状态页

| 现象 | 先检查 | 处理方法 |
| --- | --- | --- |
| 401 / Invalid API Key | 密钥是否完整、有效 | 重新复制，确认没有使用兑换码；泄露或停用的 Key 需重建 |
| 403 / 无权限 | 分组、模型白名单、客户端限制 | 换到授权分组，核对目标客户端与模型权限 |
| 404 / Not Found | 接口路径、模型 ID | 检查 /v1 重复、协议和完整 ID，区分模型不存在与路由不存在 |
| 402 / quota / 余额不足 | 账户余额、订阅和 Key 额度 | 核对到期时间与各层限额；充值不一定解除 Key 自身限额 |
| 429 / rate limit | 并发、频率、套餐限额 | 降低并发，等待限额恢复，使用逐步延长间隔的重试 |
| 400 / 参数不支持 | 上下文与工具参数 | 先去掉非必要选项，缩短对话，再逐项启用功能 |
| 5xx / 无可用渠道 | 上游状态与模型通道 | 查看状态页，稍后重试或切换到已授权的可用模型 |
| 超时 / 流式中断 | 网络、超时设置、任务长度 | 短请求验证，适当增加超时，检查代理与网络 |
| 模型列表为空 | 分组权限、列表接口支持 | 查控制台清单；客户端允许时手动填入准确 ID |
| 修改配置后没变化 | 当前供应商、旧会话、环境变量 | 保存工作，重启目标工具与终端，新建对话 |
| 有余额但不能调用 | 是否复制了另一计费分组的 Key | 核对按次 / 按量余额、订阅、Key 额度和模型权限 |

错误码是排查线索，具体原因以响应中的错误信息为准。重试前先看日志，避免把已经成功的长任务重复提交。

### 发给售后的信息模板

```
订单号：
使用工具及版本：
操作系统：
Base URL（不含密钥）：
模型 ID / 计费分组：
发生时间（北京时间）：
错误码 / 完整错误文本：
请求 ID（若有）：
已尝试的排查步骤：
附件：遮住 Key、兑换码、密码后的截图
```

## 16 · 看懂消耗与模型选择

**按次：**查看每个模型每次扣减多少站内额度。相同积分，用不同模型可以得到不同调用次数；Agent 的一次任务也不等于一次 API 请求。

**按量：**分别查看输入、输出、缓存读取和写入单价，再结合实际 Token 数与分组倍率。不同供应商对缓存 Token 是否包含在总输入统计内的定义可能不同，核算时不要重复计入。

**选模：**简单分类、基础整理和轻量问答优先测试经济档；项目分析、复杂编程和长任务再比较高能力模型。模型名称本身不能证明任务效果，使用同一条小任务实际比较更直接。

**避免误解：**“2 万积分”“2 万次”“20 亿 Token”是不同概念。原素材中的 Token 总量是估算口径，不是固定交付数量。控制台分组系数不是人民币单价，也不直接等于官方折扣。

## 17 · 验收与联系方式

- 已修改初始密码并绑定自己的邮箱。
- 余额、订阅与到期时间已核对。
- 当前 Key 的计费分组正确。
- 地址没有重复 /v1，Model ID 完整匹配。
- 工具能返回短消息，控制台能查到对应请求。
- 已核对实际扣费，再开始批量或长任务。

微信 / QQ：**36612995**；售后 QQ 群：**1056637296**，备用群 **635743604**。

[Telegram 客服 @miboyule](https://t.me/miboyule) · [客服机器人](https://t.me/Yer_kefu_bot) · [交流群](https://t.me/+dNcQ8AG7A7)

[服务状态页](https://token-status-api.qiyue999.com/status/token-status-api) · [现有飞书教程](https://qiyue999.feishu.cn/docx/T6HJdTpixo4REgxqnGlczc8rnDc)

基础教程用于自助接入；3 万、5 万、10 万积分档可免费远程配置，具体工具与服务范围拍前确认。

## 18 · 资料来源与版本说明

整理日期：2026-10-05。结合店铺 TXT、后台操作截图与旧 HTML 重写；旧教程中的他店地址、兑换码、密钥与不一致参数未沿用。文中的菜单名称可能随软件版本变化。

- [New API：CC Switch 使用说明](https://docs.newapi.pro/zh/docs/apps/cc-switch)（本次已读取）
- [OpenCode：Providers](https://opencode.ai/docs/providers/)（本次已读取）
- [Claude Code：LLM gateway](https://code.claude.com/docs/en/llm-gateway)（本次已读取）
- [Cline：OpenAI Compatible](https://docs.cline.bot/provider-config/openai-compatible)（本次已读取）
- [Codex：配置参考](https://developers.openai.com/codex/config-reference)、[高级配置](https://developers.openai.com/codex/config-advanced)（本次访问返回 403，未核验当前页面）

WorkBuddy、ZCode 及聊天客户端按本地素材与通用接入流程编写；未逐一登录各工具验证，也未使用真实 API Key 做计费请求。