LingStack 使用文档

1. 快速开始

LingStack 提供模型 API 转发与统一令牌管理。大多数工具只需要填写两项：

• Base URL: https://api.lingstackai.com/v1
• API Key: 在控制台创建的令牌，通常以 sk- 开头

1. 注册或登录 LingStack 账号。
2. 新用户注册送 1000 万 Token 测试额度，需联系管理员手动发放。
3. 进入控制台，创建 API 令牌。
4. 确认要使用的模型名称，例如 gpt-4o-mini、claude-sonnet-4-5，以控制台可用模型为准。
5. 在工具或代码里填写 Base URL、API Key 和模型名称。
6. 发送一次测试请求，再到控制台查看调用日志和额度消耗。

2. 创建令牌

进入控制台后，按下面路径创建一个新的 API Key：

控制台 -> 令牌 -> 添加令牌

建议命名方式

请不要把完整 API Key 发给客服、写入公开仓库、放进前端页面、截图发到社群，或交给不可信的浏览器插件。

3. API 地址

LingStack 线上 API 地址如下：

如果某个工具字段叫 Server URL、API Base、Endpoint、Base Path，本质上都在填写 Base URL。除 Claude Code 特别说明外，优先填写 https://api.lingstackai.com/v1。

4. 工具接入总览

如果工具里能选择 Provider 类型，优先选 OpenAI Compatible、Custom OpenAI 或 自定义 OpenAI。如果只能选择官方 OpenAI 且不能填写 Base URL，这个工具版本通常无法直接接入中转地址。

5. Claude Code 接入

Claude Code 使用 Anthropic Messages 格式。LingStack 支持该类请求时，Base URL 要填写根地址 https://api.lingstackai.com，不要在环境变量里追加 /v1。

macOS / Linux 临时配置

1. 打开终端。
2. 把下面的 sk-your-token 换成你在 LingStack 控制台创建的令牌。
3. 执行命令后，在同一个终端里启动 claude。

export ANTHROPIC_AUTH_TOKEN="sk-your-token"
export ANTHROPIC_BASE_URL="https://api.lingstackai.com"
claude

macOS / Linux 永久配置

如果你每次打开终端都想自动生效，可以写入 ~/.zshrc 或 ~/.bashrc：

echo 'export ANTHROPIC_AUTH_TOKEN="sk-your-token"' >> ~/.zshrc
echo 'export ANTHROPIC_BASE_URL="https://api.lingstackai.com"' >> ~/.zshrc
source ~/.zshrc

Windows PowerShell

setx ANTHROPIC_AUTH_TOKEN "sk-your-token"
setx ANTHROPIC_BASE_URL "https://api.lingstackai.com"

执行 setx 后需要重新打开一个 PowerShell 窗口，再运行 claude。

验证请求

进入 Claude Code 后发送一个简单任务，例如：

用一句话介绍当前项目，并列出你能看到的主要文件。

如果返回正常，再到 LingStack 控制台查看是否出现对应调用日志。

常见问题

• 404: 检查 ANTHROPIC_BASE_URL 是否误填成 https://api.lingstackai.com/v1。Claude Code 这里应填根地址。
• 401: 检查令牌是否完整、是否被禁用，变量名是否是 ANTHROPIC_AUTH_TOKEN。
• 模型不可用: 换成控制台显示可用的 Claude 模型，或联系管理员确认渠道能力。

6. Codex 接入

Codex CLI 支持在 ~/.codex/config.toml 中配置自定义模型 Provider。LingStack 按 OpenAI 兼容服务接入。

步骤 1：设置 API Key

export LINGSTACK_API_KEY="sk-your-token"

如果希望长期生效，可以写入 ~/.zshrc：

echo 'export LINGSTACK_API_KEY="sk-your-token"' >> ~/.zshrc
source ~/.zshrc

步骤 2：编辑 Codex 配置

打开或创建 ~/.codex/config.toml，加入以下配置：

model_provider = "lingstack"
model = "gpt-4o-mini"

[model_providers.lingstack]
name = "LingStack"
base_url = "https://api.lingstackai.com/v1"
env_key = "LINGSTACK_API_KEY"
wire_api = "responses"

步骤 3：启动 Codex 测试

codex

打开后输入一个低风险测试任务，例如：

请读取当前目录文件列表，并简单说明这个项目是什么。

常见问题

• 401: 终端里执行 echo $LINGSTACK_API_KEY，确认变量已经生效。
• 404 或接口不支持: 确认 base_url 是否带 /v1；如果某个模型暂不支持 Responses API，请换一个支持 Responses 的模型。
• 模型名称错误: 使用控制台模型列表里的精确名称。

7. Cursor 接入

Cursor 的设置界面会随版本变化。原则是找到模型或 API Key 设置页，填写 LingStack 的 Key 和 OpenAI 兼容 Base URL。

推荐步骤

1. 打开 Cursor。
2. 进入 Settings 或 Cursor Settings。
3. 进入 Models、API Keys 或类似页面。
4. 找到 OpenAI API Key、Custom Provider、OpenAI Compatible 或 Override OpenAI Base URL。
5. 填写 API Key = sk-your-token。
6. 填写 Base URL = https://api.lingstackai.com/v1。
7. 模型名称填写控制台可用模型，例如 gpt-4o-mini。
8. 保存后新建一个 Chat 或 Composer 会话测试。

测试提示词

请解释当前打开文件的作用，并指出一个可以改进的地方。

如果你的 Cursor 版本只能填写官方 OpenAI Key，不能填写 Base URL，那么它可能无法直接使用 LingStack 中转地址。可以升级 Cursor，或改用支持 OpenAI Compatible Provider 的客户端。

8. OpenClaw 接入

OpenClaw 若提供自定义模型或 OpenAI Compatible Provider，按下面字段填写即可。不同版本字段名称可能不同，核心值保持一致。

配置步骤

1. 打开 OpenClaw 设置页。
2. 进入 Models、Providers 或 LLM 配置。
3. 新增 Provider，类型选择 OpenAI Compatible、Custom OpenAI 或 自定义 OpenAI。
4. 填写 API Key = sk-your-token。
5. 填写 Base URL = https://api.lingstackai.com/v1。
6. 模型名称填写控制台可用模型。
7. 保存后重启当前会话，发送简单任务测试。

如果模型列表拉取失败

有些客户端不会自动读取 /v1/models，可以手动添加模型名称。模型名称必须和控制台显示保持一致。

9. Hermes 接入

Hermes 或 Hermes Agent 类工具通常支持 OpenAI 兼容环境变量，也可能提供图形化 Provider 表单。优先使用界面配置；如果没有界面，就使用环境变量。

环境变量方式

export OPENAI_API_KEY="sk-your-token"
export OPENAI_BASE_URL="https://api.lingstackai.com/v1"
export MODEL="gpt-4o-mini"

.env 文件方式

OPENAI_API_KEY=sk-your-token
OPENAI_BASE_URL=https://api.lingstackai.com/v1
MODEL=gpt-4o-mini

界面方式

1. 进入 Hermes 的 Provider、Model 或 LLM 设置。
2. Provider 类型选择 OpenAI 或 OpenAI Compatible。
3. API Key 填 LingStack 令牌。
4. Base URL 填 https://api.lingstackai.com/v1。
5. 模型名称填控制台可用模型，保存后重启 Agent。

如果你的 Hermes 版本变量名叫 OPENAI_API_BASE、API_BASE_URL 或 BASE_URL，填写同一个 LingStack 地址即可。

10. 其他客户端

不同客户端字段名略有差异。看到 Endpoint、API Host、Server URL、Base Path 时，都可以按 Base URL 理解。

11. API 示例

查看模型列表

curl https://api.lingstackai.com/v1/models \
  -H "Authorization: Bearer sk-your-token"

Chat Completions

curl https://api.lingstackai.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-your-token" \
  -d '{
    "model": "gpt-4o-mini",
    "messages": [
      {"role": "system", "content": "你是一个简洁可靠的助手。"},
      {"role": "user", "content": "用一句话介绍你自己。"}
    ]
  }'

Responses API

curl https://api.lingstackai.com/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-your-token" \
  -d '{
    "model": "gpt-4o-mini",
    "input": "请生成一个简短标题。"
  }'

JavaScript SDK

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.LINGSTACK_API_KEY,
  baseURL: "https://api.lingstackai.com/v1",
});

const completion = await client.chat.completions.create({
  model: "gpt-4o-mini",
  messages: [
    { role: "user", content: "写一句产品文案。" },
  ],
});

console.log(completion.choices[0].message.content);

Python SDK

from openai import OpenAI

client = OpenAI(
    api_key="sk-your-token",
    base_url="https://api.lingstackai.com/v1",
)

completion = client.chat.completions.create(
    model="gpt-4o-mini",
    messages=[
        {"role": "user", "content": "写一句产品文案。"}
    ],
)

print(completion.choices[0].message.content)

12. 额度与计费

每次请求会根据模型、输入、输出、缓存、图片、音频或其他能力计算消耗。实际扣费以控制台记录为准。

• 不同模型倍率不同。
• 长上下文和大输出会消耗更多额度。
• 流式输出和普通输出的最终消耗通常取决于实际 token 数。
• 图片、语音、视频等多模态任务可能按次或按模型规则计费。

新用户注册送 1000 万 Token 测试额度，需联系管理员手动发放；发放后建议先用小额度令牌进行测试。

13. 常见错误

14. 使用规范

• 不要共享、转卖、公开分发个人令牌。
• 不要用于违法、侵权、欺诈、垃圾信息或绕过安全限制的场景。
• 不要进行异常高并发压测，除非提前获得许可。
• 不要提交敏感个人信息、密码、密钥、身份证件等内容。
• 不要尝试攻击、扫描、绕过或破坏本站及上游服务。

违反规则的账号或令牌可能会被限制、暂停或删除。

15. 数据与隐私

平台可能记录必要的调用元数据，用于计费、排障和安全审计，例如请求时间、账号、令牌、模型名称、状态码、消耗额度和错误信息。

请不要在请求中提交不必要的敏感信息。不同上游模型服务可能有各自的数据处理政策，具体以对应服务条款为准。

16. 稳定性建议

• 为不同业务创建独立令牌。
• 设置合理的额度和限流。
• 在客户端实现超时、重试和降级。
• 对重要请求记录 request id 或业务 id。
• 避免把所有业务绑定到单一模型。

17. 官方参考

不同工具的字段名称可能会随版本调整。本文档接入方式参考了以下官方资料，并结合 LingStack 当前线上接口整理：

• Claude Code LLM gateway
• OpenAI Codex config reference
• Cursor API Keys

18. 联系支持

如果遇到问题，请提供账号用户名、请求时间、使用模型、错误状态码、控制台日志截图和 request id。请不要发送完整 API Key，只需要提供令牌名称或末尾几位即可。