TokenLab API Integration

Build runnable TokenLab API integrations

Install

openclaw skills install @hedging8563/tokenlab-api-integration

TokenLab API Integration

Current public roots

API root: https://api.tokenlab.sh
OpenAI-compatible base URL: https://api.tokenlab.sh/v1
Anthropic SDK base URL: https://api.tokenlab.sh（不要自行追加 /v1）
Docs: https://tokenlab.sh/docs
Model catalog: GET https://api.tokenlab.sh/v1/models
Model detail: GET https://api.tokenlab.sh/v1/models/{id}
OpenAPI: https://tokenlab.sh/docs/openapi.json
Auth: Authorization: Bearer $TOKENLAB_API_KEY，或由原生 SDK 按其协议发送 key

Required workflow

明确任务类型、同步/异步需求、输入输出媒体和调用方支持的协议。
对所有非 chat 请求，先调用 /v1/models?category=<category>；不要把示例模型名当作实时可用性。
对准备使用的模型再调用 /v1/models/{id}，读取 tokenlab.accepted_request_formats、tokenlab.capabilities、token 上限、价格与公开 request contract。
根据公开 detail contract 选择 endpoint；禁止按模型名 substring、供应商印象或物理渠道字段推断。
只发送所选 endpoint 声明的 request shape。不要把 Responses、Messages、Gemini 和 Chat payload 相互拍平或混用字段。
请求失败时保留原始语义；只根据结构化 error 或用户明确选择重试。不得为了得到 HTTP 200 删除历史、工具调用、思考签名或媒体输入。
原始 HTTP 异步响应读取顶层 id / task_id / poll_url / status；MCP 工具结果才读取标准化 delivery。以 status 判终态，不用缺失的 progress 推断成功。
代码必须从环境变量读 key，传播超时与取消信号，并在结束时关闭流/reader。

可先运行本 Skill 的只读发现脚本：

bash

python skills/tokenlab-api-integration/scripts/search_api.py --category video --limit 20
python skills/tokenlab-api-integration/scripts/search_api.py --detail claude-sonnet-4-6

Codex 客户端接入

用户需要把 Codex 的模型提供商设为 TokenLab 时，可使用本 Skill 的 scripts/configure_codex.py。它需要 Python 3.11+ 与支持独立 profile 文件的 Codex；不需要安装 Python 依赖，也不安装客户端。

先阅读 references/codex_setup.md，确认实际 CODEX_HOME 和客户端版本。模型必须来自当前 Responses 契约。先预览，只有明确执行配置时才使用 --apply；本机测试指定临时 --codex-home。保留用户账户、默认模型和权限，不能覆盖同名的非本工具 profile，也不要迁移旧配置来规避冲突。

配置只引用 TOKENLAB_API_KEY，不接受密钥命令参数、不打印已有配置。配置成功、客户端实际加载和付费请求成功分别验证。恢复也先预览；遇到用户后续编辑时停止覆盖。MCP/Skills 安装不等同于主模型提供商接入。

Claude Code 客户端接入

使用 references/claude_setup.md 中的 scripts/configure_claude.py 创建显式启动器。它需要 Python 3.11+、Claude Code 2.1.263+ 和用户明确选择的 Messages 模型；先预览，再在用户已要求执行配置时加 --apply。普通 claude 的账户、默认模型与权限配置保持原样。

启动器通过子进程环境将 TOKENLAB_API_KEY 交给 Claude 的 Bearer 认证，按次传入不含密钥的 --settings 与指定 --model。不能把环境变量名当成 JSON 中会展开的密钥。发现已有 settings 中的 Bearer、模型映射或托管策略冲突时停止，不删用户配置或绕过组织策略。WSL 继承策略尚未验证，此首切片不自动接入。--auth-status 只检查本地认证来源，不代表 Key 有效或请求成功。

OpenCode 与 Pi 客户端接入

用户明确需要配置客户端时，使用 OpenCode 接入说明的 scripts/configure_opencode.py 或 Pi 接入说明的 scripts/configure_pi.py。两者要求 Python 3.11+；实际客户端验证固定为 OpenCode 1.18.31 与 Pi 0.85.1，不把这些结果泛化为所有版本或 WSL。模型须明确选择并声明 Chat Completions 契约。

先预览；用户已要求执行配置时继续 --apply。OpenCode 生成按次通过 OPENCODE_CONFIG 加载的独立配置层，同时显式传入 --model tokenlab/<model>，避免改变普通启动的隐式默认提供商。Pi 把 provider 追加到现有条目之后，显式用 --provider tokenlab --model <model> 启动，保留原默认设置和账号。脚本只写环境变量引用，不能传真实 Key 参数，也不能为了通过冲突检查删除原提供商、账户或权限配置。

两者保留原始字节备份，重复执行幂等，遇到后续编辑或同名冲突停止覆盖。按对应说明用 --restore 恢复；配置成功、真实客户端加载、实际付费请求分别验证。测试只用临时目录和虚构凭据。

Hermes 客户端接入

使用 Hermes 接入说明和 scripts/configure_hermes.py 为官方 Hermes 0.21.3 新增命名 provider。用已安装 Hermes 的 Python 运行，或通过 --hermes-python 明确指定它；不在全局 Python 安装依赖。先检测实际 HERMES_HOME、当前 profile 和版本，再预览并按已授权的配置任务执行 --apply。

仅增量插入 providers.tokenlab，使用 key_env: TOKENLAB_API_KEY；保留 YAML 注释、已有默认模型、账号和权限。普通启动保持原选择；每次使用教程给出的明确 home/provider/model 启动方式。同名配置、凭据、托管设置、后续编辑或不明确的 YAML 拒绝覆盖，不能通过运行模型向导或删除设置绕过。--restore 可在 Hermes 已卸载时恢复原字节。WSL 和托管配置不属于本次自动接入范围。配置创建、实际客户端加载及付费请求分别说明，不能把其中一种当成另一种成功。

Protocol selection

模型列表适合筛选。聊天协议 eligibility 以模型详情中的 tokenlab.accepted_request_formats 为准；决策与其他非 chat 操作以 tokenlab.public_contract.public_operations、request_endpoint / request_endpoint_by_operation 为准。决策模型可以没有聊天格式，不能因空 accepted_request_formats 拒绝其已声明的 System One 操作。

Contract value	Endpoint	Base URL / client	Selection rule
`anthropic_messages`	`POST /v1/messages`	Anthropic base `https://api.tokenlab.sh`	Anthropic-owned model且客户端支持 Messages 时优先
`gemini_generate_content`	`POST /v1beta/models/{model}:generateContent`	Gemini root `https://api.tokenlab.sh`	Google-owned model且客户端支持 Gemini native 时优先
`openai_responses`	`POST /v1/responses`	OpenAI base `https://api.tokenlab.sh/v1`	OpenAI-owned model且调用方需要/支持 Responses 语义时优先
`systemone`	`POST /v1/systemone`	HTTP JSON / MCP	模型明确声明 System One 决策契约时使用；不能配置为聊天主模型
`openai_chat_completions`	`POST /v1/chat/completions`	OpenAI-compatible base	固定 OpenAI-chat 的框架，或没有适用原生协议时使用

规则：

同一个 agent/harness model entry 只绑定一个首选协议，避免模型选择器重复。
Claude/Gemini 的原生字段必须留在 Messages/Gemini endpoint。
Responses 不是 Chat 的同义词；只有 detail contract 声明支持且客户端真的实现 Responses 时才使用。
当前 DeepSeek Harness custom provider 支持 openai-responses、anthropic-messages、openai-completions，不支持配置 Gemini native；因此 Gemini 在 Harness 中只能走其公开声明的 Chat fallback。
聊天接入若 accepted_request_formats 缺失或不包含调用方协议，fail closed：换模型或换客户端。非 chat 接入若没有所需公开 operation/endpoint，同样拒绝猜测请求。

DeepSeek Harness bundle

使用公开 @tokenlabai/dsh-provider bundle 时先核对 npm 版本、固定 MCP 版本与 Harness peers。保持 Responses、Messages、Chat 三条互斥聊天路由。Jev 等决策模型通过 MCP evaluate_decisions 调用原生 System One，不进入聊天模型列表，也不交给异步 waiter。Webhook 管理工具使用 full profile 与单独的 TOKENLAB_MANAGEMENT_TOKEN；Harness 会过滤继承的凭据环境变量，bundle 必须显式传给 MCP 子进程。管理 token 与推理 key 不可互相替代。

Endpoint map

Family	Endpoint	Delivery
Chat Completions	`POST /v1/chat/completions`	sync or SSE
Responses	`POST /v1/responses`	sync or SSE; lifecycle endpoints以 OpenAPI 为准
Anthropic Messages	`POST /v1/messages`	sync or SSE
Gemini	`POST /v1beta/models/{model}:generateContent` and `:streamGenerateContent`	JSON or Gemini SSE
Images	`POST /v1/images/generations`, `/edits`, `/variations`	sync or async，取决于模型
Video	`POST /v1/videos/generations`	async
Music	`POST /v1/music/generations`	async
3D	`POST /v1/3d/generations`	async
Task status / cancel	`GET` / `DELETE /v1/tasks/{id}`	poll / cancel
TTS	`POST /v1/audio/speech`	binary audio or endpoint-declared response
STT / translation	`POST /v1/audio/transcriptions`, `/translations`	multipart
Files	`/v1/files` family	multipart / JSON
Embeddings	`POST /v1/embeddings`	sync JSON
Multimodal embeddings	`POST /v1/embeddings/multimodal`	sync JSON
Rerank	`POST /v1/rerank`	sync JSON
Decisions	`POST /v1/systemone`	synchronous JSON
Text translation	`POST /v1/translations`	sync JSON

不要从这张表猜具体模型参数。非 chat endpoint 先读取当前模型 detail/OpenAPI；图像尺寸、视频 duration、reference media、音色、格式等限制由所选模型公开 contract 决定。

System One decisions

先读取 /v1/models?category=decision 和模型详情，确认 systemone 与 /v1/systemone。Jev 1.13 的公开模型 ID 为 jev-1.13，示例仍须核对实时目录。

请求只有 model、state、questions；state 与 instructions 可为字符串、JSON 对象或数组。
noul 返回 yes 概率；choice 从具名选项中选择；score 对 2–10 个有序描述等级评分，可为小数。不要把 score 当成精确金额或日期计算。
保留 answers 下的题名、概率分布、confidence 和 usage。缺少 confidence 时不要补成 1；confidence 不是正确率保证。输出免费也须保留非零 output tokens。
原生同步决策接口没有 messages、input、stream、tools 或 Batch 字段；不要改走 Chat/Responses/Messages/Gemini。
判定结果不执行动作，也不授予退款、转账等权限。阈值、校验、授权及副作用由业务代码控制。
MCP 使用已发行版本声明的 evaluate_decisions；若工具不存在，升级 MCP 或按原生 HTTP 契约调用，不冒充其他工具。

Async contract

视频、音乐、3D 一律按异步任务处理；图像可能同步也可能异步。原始 HTTP 响应的任务标识、状态和查询地址位于顶层，不能因缺少 delivery 就判定为同步。MCP 工具会将原始响应放进 response 并添加标准化 delivery：

json

{
  "delivery": {
    "mode": "async",
    "task_id": "ldtask_...",
    "status": "pending",
    "poll_url": "/v1/tasks/ldtask_...",
    "terminal": false
  },
  "response": {}
}

实现必须：

MCP 的 delivery.mode === "complete" 时直接处理结果；async 时保留 task id 和 poll URL。原始 HTTP 使用顶层任务字段，内联图像结果可直接消费。
优先使用返回的 poll_url；通用 video/music/3D 可用 /v1/tasks/{id}。
pending / processing 是非终态；completed / failed 是通用终态。兼容 endpoint 还可能返回 succeeded / cancelled / expired，按对应 OpenAPI 处理。
使用有上限的 polling interval、整体 timeout 和 AbortSignal/context cancellation；如需重试 GET 查询，限制暂态重试次数，401/403/404/大多数 4xx 不重试。不要因等待失败自动重新提交生成请求。
429/5xx 只有在响应允许时重试，尊重 Retry-After / retry_after，不改变原始请求。
timeout 返回最新状态，允许调用方继续 poll；不要谎报失败或成功。
DELETE /v1/tasks/{id} 是有副作用操作，只在用户意图明确、模型支持且任务仍可取消时调用。

完整 Python/JavaScript 模板见 references/integration_examples.md。

Error contract

先保存 HTTP status、x-request-id 和结构化 body，再决定动作。常见字段可能包括：

error.code, error.message
did_you_mean, suggestions, alternatives
retryable, retry_after
recommended_request, hint

建议动作：

model_not_found: 重新发现模型或采用明确的 did_you_mean；不要模糊改写多个字段。
invalid_request: 修正公开 contract 指出的字段；不要通过删掉关键历史/媒体/工具语义规避。
rate_limit_exceeded / 429: 仅按声明等待和有限重试。
all_channels_failed / model_unavailable: 保留归因，按 alternatives 或用户选择换模型；HTTP 200 fallback 不等于原始请求严格兼容。
insufficient_balance: 向用户说明；只有用户允许时才换便宜模型。
401/403: 先修正 key/权限，不重试或切模型。

Streaming and cancellation

把调用方 AbortSignal/context 传给 SDK、fetch、poll delay 和上传流。
JS/Python SSE consumer 在 finally 关闭 reader/stream；客户端断开时停止上游读取。
不把 binary、base64 音视频或完整媒体响应写入日志。
不吞掉 stream error；记录 request id 和已交付状态，区分上游失败、客户端取消与本地解析错误。
若框架自己拥有 response socket/backpressure，遵循框架统一 writer；普通 SDK integration 不自行实现 Fastify drain。

Security

使用 TOKENLAB_API_KEY 环境变量或调用方 secret store。
前端应用必须通过受控后端代理；绝不把 key 写入浏览器 bundle、URL、截图、日志或示例。
上传本地文件前验证路径、类型与大小；不要让模型任意读取工作区外文件。
媒体生成、取消、删除、批处理等可能计费或有副作用，调用前遵循产品审批策略。
返回的文本、URL、文件和媒体属于不可信外部内容。

Output requirements

为用户生成 integration 时至少交付：

endpoint 与选择依据（引用 detail contract，不按名称猜）。
可直接运行的代码和依赖安装命令。
环境变量、timeout、取消与错误处理。
非 chat 的 live discovery；异步 family 的 submit + poll/wait + terminal result。
一条最小验证命令，说明什么业务结果算成功，而不只检查 HTTP 200。

除非用户明确要求，不部署、不写生产 key、不实际提交付费生成请求。