# LingStack 使用文档

本文档适用于 LingStack 提供的模型接口、令牌管理、AI 工具接入和相关数字服务。

## 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. 创建令牌

进入：

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

![LingStack 控制台创建令牌示意图](assets/guides/token-console.svg)

建议为不同用途创建不同令牌：

| 用途 | 令牌名示例 | 建议 |
| --- | --- | --- |
| 个人开发 | `personal-dev` | 设置较小额度，适合测试。 |
| Cursor | `cursor-dev` | 单独观察编辑器消耗。 |
| Claude Code | `claude-code` | 用于终端代理工具，泄露后可单独禁用。 |
| 线上服务 | `server-prod` | 建议设置限额和告警。 |

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

## 3. API 地址

LingStack 线上 API 地址如下：

| 类型 | 地址 |
| --- | --- |
| OpenAI 兼容地址 | `https://api.lingstackai.com/v1` |
| Anthropic 兼容根地址 | `https://api.lingstackai.com` |
| 文档地址 | `https://docs.lingstackai.com` |

![OpenAI 兼容地址和 Anthropic 兼容地址选择示意图](assets/guides/endpoint-choice.svg)

如果某个工具字段叫 Server URL、API Base、Endpoint、Base Path，本质上都在填写 Base URL。除 Claude Code 特别说明外，优先填写：

```text
https://api.lingstackai.com/v1
```

## 4. 工具接入总览

| 工具 | 接口类型 | Base URL | Key 字段 |
| --- | --- | --- | --- |
| Claude Code | Anthropic Messages | `https://api.lingstackai.com` | `ANTHROPIC_AUTH_TOKEN` |
| Codex | OpenAI Compatible | `https://api.lingstackai.com/v1` | `LINGSTACK_API_KEY` |
| Cursor | OpenAI Compatible | `https://api.lingstackai.com/v1` | OpenAI API Key 或自定义 Provider Key |
| OpenClaw | OpenAI Compatible | `https://api.lingstackai.com/v1` | API Key |
| Hermes | OpenAI Compatible | `https://api.lingstackai.com/v1` | `OPENAI_API_KEY` |

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

## 5. Claude Code 接入

Claude Code 使用 Anthropic Messages 格式。LingStack 支持该类请求时，Base URL 要填写根地址：

```text
https://api.lingstackai.com
```

不要在 `ANTHROPIC_BASE_URL` 里追加 `/v1`。

![Claude Code 终端配置示意图](assets/guides/claude-code-terminal.svg)

### macOS / Linux 临时配置

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

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

### macOS / Linux 永久配置

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

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

### Windows PowerShell

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

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

### 验证请求

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

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

如果返回正常，再到 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 兼容服务接入。

![Codex config.toml 配置 LingStack Provider 示意图](assets/guides/codex-config.svg)

### 步骤 1：设置 API Key

```bash
export LINGSTACK_API_KEY="sk-your-token"
```

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

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

### 步骤 2：编辑 Codex 配置

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

```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 测试

```bash
codex
```

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

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

### 常见问题

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

## 7. Cursor 接入

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

![Cursor 模型设置接入 LingStack 示意图](assets/guides/cursor-settings.svg)

推荐步骤：

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 会话测试。

测试提示词：

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

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

## 8. OpenClaw 接入

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

![OpenClaw OpenAI Compatible Provider 设置示意图](assets/guides/openai-compatible-provider.svg)

配置步骤：

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. 保存后重启当前会话，发送简单任务测试。

如果模型列表拉取失败，可以手动添加模型名称。模型名称必须和控制台显示保持一致。

## 9. Hermes 接入

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

![Hermes Agent 通过环境变量接入 LingStack 示意图](assets/guides/hermes-provider.svg)

### 环境变量方式

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

### .env 文件方式

```dotenv
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. 其他客户端

### Cherry Studio

```text
API Key: sk-your-token
API Base URL: https://api.lingstackai.com/v1
```

### LobeChat

```text
API Key: sk-your-token
Base URL: https://api.lingstackai.com/v1
```

### NextChat / ChatGPT Next Web

```text
OPENAI_API_KEY=sk-your-token
BASE_URL=https://api.lingstackai.com
```

### OpenAI SDK

```text
apiKey: sk-your-token
baseURL: https://api.lingstackai.com/v1
```

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

## 11. API 示例

### 查看模型列表

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

### Chat Completions

```bash
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

```bash
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

```js
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

```python
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. 常见错误

| 状态码 | 常见原因 | 处理建议 |
| --- | --- | --- |
| 401 | API Key 填错、令牌禁用、请求头缺失 | 检查 `Authorization: Bearer sk-...` 或工具里的 Key 字段。 |
| 403 | 无权访问模型、套餐不支持、触发风控 | 更换模型或联系管理员确认账号权限。 |
| 404 | Base URL 填错、路径重复或缺少 `/v1` | OpenAI 兼容工具用 `/v1`，Claude Code 用根地址。 |
| 429 | 频率过高、并发过高、上游限流 | 降低并发，增加重试间隔，使用指数退避。 |
| 500 / 502 / 503 | 上游异常、网络波动、模型暂时不可用 | 稍后重试或更换模型，并查看控制台日志。 |

## 14. 使用规范

为了保障服务稳定，请遵守以下规则：

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

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

## 15. 数据与隐私

平台可能记录必要的调用元数据，用于计费、排障和安全审计，例如：

- 请求时间
- 使用账号
- 使用令牌
- 模型名称
- 状态码
- 消耗额度
- 错误信息

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

## 16. 稳定性建议

生产业务建议：

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

## 17. 官方参考

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

- [Claude Code LLM gateway](https://code.claude.com/docs/en/llm-gateway)
- [OpenAI Codex config reference](https://developers.openai.com/codex/config-reference)
- [Cursor API Keys](https://docs.cursor.com/zh/settings/api-keys)

## 18. 联系支持

如果遇到问题，请提供以下信息，方便排查：

- 账号用户名
- 请求时间
- 使用模型
- 错误状态码
- 控制台日志截图
- request id，如有

请不要发送完整 API Key。只需要提供令牌名称或末尾几位即可。