# 客户端接入指南

LosPool 对外只提供一个 **OpenAI Chat Completions 兼容**入口：

| 项目 | 值 |
|---|---|
| Base URL | `http://47.111.175.191:8790/v1`（以后套了域名/HTTPS 就换成 `https://<域名>/v1`） |
| 管理台 | `http://47.111.175.191:8790/admin` |
| API Key | 管理台「用户与 key」里创建的 `sk-pool-...` |
| 默认模型 | `pool-standard`（写代码推荐）或 `pool-auto`（按内容自动分档） |

> 端口说明：本仓库 `docker-compose.yml` 把宿主机 **8790** 映射到容器 8787，所以从服务器外面访问一律用 **8790**。
> 只有在服务器本机上直接 `node src/server.mjs`（没有 Docker）时才是 8787。
> 本文统一用这台服务器 `http://47.111.175.191:8790`；如果以后换了地址，整体替换即可。

先用 curl 确认网络和 key 都没问题：

```bash
export LOSPOOL_KEY=sk-pool-你的key
export LOSPOOL_HOST=http://47.111.175.191:8790

curl -s $LOSPOOL_HOST/v1/chat/completions \
  -H "authorization: Bearer $LOSPOOL_KEY" \
  -H "content-type: application/json" \
  -d '{"model":"pool-standard","messages":[{"role":"user","content":"ping"}]}'
```

## 模型名怎么选

| 模型名 | 实际档位 | 适合 |
|---|---|---|
| `pool-auto` | 自动判断 | 日常混合使用；可能落到 cheap |
| `pool-cheap` | cheap | 短问答、整理、简单工具调用 |
| `pool-standard` | standard | **写代码 / 长文 / 多步任务，推荐 CLI 默认** |
| `pool-max` | max | 复杂重构、深度分析；最慢也最贵 |
| `pool-long` | long | 仓库大、上下文超过 100K |
| `pool-vision` | vision | 带图片的请求 |
| `pool-app` | app | 要稳定正文输出、不希望思考把额度烧光 |

几点说明：

- 用户在白名单里必须包含对应档位，否则请求会被拒绝或降级。
- `pool-auto` 自动升级到 max 默认是关闭的（避免长时间等待）。需要顶配时直接写 `pool-max`，或在消息开头加 `@max`；也可以给服务端设 `LOSPOOL_AUTO_MAX=on`。
- **写代码的 CLI（Codex / Claude Code / OpenCode）依赖函数调用（tools）**。如果 `pool-auto` 恰好落到不支持工具的 cheap 模型，CLI 会报错或行为异常。建议默认钉死 `pool-standard`，难任务再切 `pool-max`。
- 所有请求都有每日 token 配额；超了返回 429。

---

## OpenCode

OpenCode 原生支持 OpenAI 兼容 provider，**不需要装任何中间层**，直接连 LosPool。

配置文件放在全局 `~/.config/opencode/opencode.json`，或项目根目录的 `opencode.json`：

```json
{
  "$schema": "https://opencode.ai/config.json",
  "model": "lospool/pool-standard",
  "provider": {
    "lospool": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "LosPool",
      "options": {
        "baseURL": "http://47.111.175.191:8790/v1",
        "apiKey": "{env:LOSPOOL_KEY}"
      },
      "models": {
        "pool-auto":     { "name": "LosPool 自动",   "tool_call": true },
        "pool-cheap":    { "name": "LosPool 省钱",   "tool_call": true },
        "pool-standard": { "name": "LosPool 标准",   "tool_call": true },
        "pool-max":      { "name": "LosPool 顶配",   "tool_call": true },
        "pool-long":     { "name": "LosPool 长文",   "tool_call": true },
        "pool-app":      { "name": "LosPool 应用",   "tool_call": true }
      }
    }
  }
}
```

```bash
export LOSPOOL_KEY=sk-pool-你的key
opencode
```

进去后用 `/models` 选择 `LosPool 标准` 等模型。`{env:LOSPOOL_KEY}` 表示从环境变量读取；如果不写 `options.apiKey`，也可以运行 `opencode auth login`，选 **Other**，provider id 填 `lospool`，再输入 key。

> 注意别漏了 `/v1`。目前服务器是 **HTTP 明文**，`sk-pool-...` 会在公网上明文传输，只适合自己人小范围用；条件允许时尽快套 HTTPS（Nginx/Caddy 反代到 8790），然后全局改成 `https://域名/v1`。

---

## Codex CLI

Codex 的情况要分版本：

- **老版本**支持 `wire_api = "chat"`，可以直接连 LosPool。
- **较新的 Codex（约 v0.130+）只走 Responses API（`/v1/responses`）**，而 LosPool 只实现了 `/v1/chat/completions`。这时需要一个 Responses → Chat 的转换层，推荐用 LiteLLM（见下一节的配置）。

先看版本：

```bash
codex --version
```

### 方式 A：老版本 Codex，直接连

`~/.codex/config.toml`：

```toml
model = "pool-standard"
model_provider = "lospool"

[model_providers.lospool]
name = "LosPool"
base_url = "http://47.111.175.191:8790/v1"
env_key = "LOSPOOL_KEY"
wire_api = "chat"
```

```bash
export LOSPOOL_KEY=sk-pool-你的key
codex
```

如果启动时报 `wire_api = "chat" is no longer supported`，说明你的 Codex 已经移除 Chat 支持，改用方式 B。

### 方式 B：新版 Codex，通过 LiteLLM 转换

先用下面的 [LiteLLM 配置](#litellm-统一转换层) 在本机起一个 `4000` 端口。然后 `~/.codex/config.toml` 改成：

```toml
model = "pool-standard"
model_provider = "lospool"

[model_providers.lospool]
name = "LosPool (LiteLLM)"
base_url = "http://127.0.0.1:4000/v1"
env_key = "LITELLM_MASTER_KEY"
wire_api = "responses"
```

```bash
export LITELLM_MASTER_KEY=sk-litellm-local
codex
```

Codex 会请求 LiteLLM 的 `/v1/responses`，LiteLLM 把它转换成 `/v1/chat/completions` 再发给 LosPool。模型名仍然写 `pool-standard` / `pool-max` 这些别名。

> 如果 Codex 提示找不到模型元数据，一般只是警告；仍可继续使用。若你的版本强制要求模型在 catalog 里，先在 LiteLLM 的 `model_list` 里加一个 Codex 认识的 `model_name`（比如 `gpt-5-codex`），再把 `litellm_params.model` 指到 `custom_openai/pool-standard`，Codex 里写这个 `model_name` 即可。

---

## Claude Code

Claude Code 使用 **Anthropic Messages API（`/v1/messages`）**，LosPool 使用的是 OpenAI Chat Completions，两者协议不同，所以 **不能直接把 `ANTHROPIC_BASE_URL` 指向 LosPool**。需要中间层做协议转换，推荐同样是 LiteLLM（它也提供 `/v1/messages` 到 Chat Completions 的转换）。

### 1. 启动 LiteLLM

按下面的 [LiteLLM 配置](#litellm-统一转换层) 起服务，监听 `4000`。

### 2. 配置 Claude Code

写进 `~/.claude/settings.json`（推荐，别写项目里的 `.claude/settings.json`，那个会被提交）：

```json
{
  "env": {
    "ANTHROPIC_BASE_URL": "http://127.0.0.1:4000",
    "ANTHROPIC_AUTH_TOKEN": "sk-litellm-local",
    "ANTHROPIC_MODEL": "pool-standard",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "pool-standard",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "pool-max",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "pool-cheap",
    "CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS": "1"
  }
}
```

或者临时用 shell 变量：

```bash
unset ANTHROPIC_API_KEY          # 避免和 AUTH_TOKEN 冲突
export ANTHROPIC_BASE_URL=http://127.0.0.1:4000
export ANTHROPIC_AUTH_TOKEN=sk-litellm-local
export ANTHROPIC_MODEL=pool-standard
export ANTHROPIC_DEFAULT_SONNET_MODEL=pool-standard
export ANTHROPIC_DEFAULT_OPUS_MODEL=pool-max
export ANTHROPIC_DEFAULT_HAIKU_MODEL=pool-cheap
export CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1
claude
```

注意：

- `ANTHROPIC_BASE_URL` 只写到网关根地址，**不要带 `/v1`**；Claude Code 会自己拼 `/v1/messages`。
- `ANTHROPIC_AUTH_TOKEN` 会被放进 `Authorization: Bearer ...`，这里填 LiteLLM 的 master key。
- `ANTHROPIC_DEFAULT_HAIKU_MODEL` 用于小任务；如果小模型不支持工具导致报错，把它也改成 `pool-standard`。
- 进 Claude Code 后运行 `/status`，确认 Base URL 和模型；用 `/model` 切换档位。
- 某些第三方网关会对 Anthropic beta 头报 400，`CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1` 就是用来关掉这些实验特性的。

### 备选：claude-code-router

不想装 LiteLLM 的话，也可以用 [claude-code-router](https://github.com/musistudio/claude-code-router)。它专门把 Claude Code 的请求翻译成 OpenAI Chat Completions。

```bash
npm install -g @musistudio/claude-code-router
```

`~/.claude-code-router/config.json`：

```json
{
  "Providers": [
    {
      "name": "lospool",
      "api_base_url": "http://47.111.175.191:8790/v1/chat/completions",
      "api_key": "sk-pool-你的key",
      "models": ["pool-auto", "pool-cheap", "pool-standard", "pool-max", "pool-long"]
    }
  ],
  "Router": {
    "default": "lospool,pool-standard",
    "background": "lospool,pool-cheap",
    "think": "lospool,pool-max",
    "longContext": "lospool,pool-long",
    "longContextThreshold": 100000
  }
}
```

```bash
ccr code
```

---

## LiteLLM 统一转换层

Codex（新版）和 Claude Code 都可以共用这一套：LiteLLM 用 `custom_openai/` 前缀把上游当成 OpenAI 兼容服务，并且会把 `/v1/responses`、`/v1/messages` 转换成 `/v1/chat/completions`。

完整示例：[`docs/litellm.example.yaml`](litellm.example.yaml)。

```yaml
model_list:
  - model_name: pool-auto
    litellm_params:
      model: custom_openai/pool-auto
      api_base: http://47.111.175.191:8790/v1
      api_key: os.environ/LOSPOOL_KEY

  - model_name: pool-cheap
    litellm_params:
      model: custom_openai/pool-cheap
      api_base: http://47.111.175.191:8790/v1
      api_key: os.environ/LOSPOOL_KEY

  # ... pool-standard / pool-max / pool-long / pool-app 同理
```

安装并启动：

```bash
export LOSPOOL_KEY=sk-pool-你的key
export LITELLM_MASTER_KEY=sk-litellm-local

python3 -m venv .venv && . .venv/bin/activate
pip install 'litellm[proxy]'

litellm --config docs/litellm.example.yaml --port 4000
```

验证：

```bash
curl -s http://127.0.0.1:4000/v1/models \
  -H "authorization: Bearer $LITELLM_MASTER_KEY"
```

应该能看到 `pool-auto`、`pool-standard`、`pool-max` 等模型。

> LiteLLM 在**运行 Codex / Claude Code 的那台机器**上启动，`api_base` 指到服务器 `http://47.111.175.191:8790/v1`。
> 例外：如果 LiteLLM 和 LosPool 跑在同一台服务器上，`api_base` 用 `http://127.0.0.1:8787/v1` 更稳、也不走公网。
> 生产环境建议把 LiteLLM 也放到 HTTPS 后面，并换成真正的随机 key。

---

## 常见问题

**401 无效 key**
key 不对，或用户被停用。到管理台「用户与 key」复制完整的 `sk-pool-...`。旧版用户如果只显示「仅存前缀」，说明数据库里只有哈希，原 key 找不回，点「生成新 key」重新发一把。

**429 额度用完**
该用户当天 token 到上限了，第二天自动重置；管理员可以在用户列表里「改额度」（0 = 不限）。

**CLI 报工具/函数调用错误**
把模型钉死到 `pool-standard` 或 `pool-max`，不要用 `pool-auto`；并确认白名单里有该档位。

**上下文太长 / 400 context length**
用 `pool-long`，或让用户改大上游模型的上下文。LosPool 会根据消息估算长度自动切到 long，但客户端直接点名 `pool-long` 更稳。

**流式输出卡住或断开**
LosPool 支持 SSE；如果中间有 Nginx 等反向代理，关闭响应缓冲（`proxy_buffering off`）并放宽超时。

**安全提醒**
公网部署请套 HTTPS。HTTP 明文会同时暴露 `sk-pool-...` 和上游 key。

---

## 参考

- [Codex 配置参考](https://developers.openai.com/codex/config)
- [OpenCode Providers](https://opencode.ai/docs/providers/)
- [Claude Code 环境变量](https://code.claude.com/docs/en/env-vars)
- [LiteLLM Proxy](https://docs.litellm.ai/docs/proxy/quick_start)
- [LiteLLM `/v1/responses`](https://docs.litellm.ai/docs/response_api)
- [claude-code-router](https://github.com/musistudio/claude-code-router)