07-client-usage

07. 客户端使用 §

CPA 同时暴露 OpenAI / Gemini / Claude / Codex 兼容协议，端口都是 8317。下游客户端按它原生协议来就行。

通用约定 §

• Base URL：http://你的服务器IP:8317（建议套 HTTPS，详见 10-security.md）
• API key：config.yaml 里 api-keys 列出的任意一个
• 协议路由：客户端发什么协议（OpenAI/Gemini/Claude），CPA 自动识别并转发到合适的上游

OpenAI 兼容协议 §

curl http://你的服务器IP:8317/v1/chat/completions \
  -H "Authorization: Bearer 你的api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5",
    "messages": [{"role":"user","content":"hello"}]
  }'

可用模型列表：

curl -s http://你的服务器IP:8317/v1/models \
  -H "Authorization: Bearer 你的api-key" | python3 -m json.tool

模型名取决于你登录了哪些上游凭据：

上游	常见模型名
Codex (ChatGPT)	gpt-5, gpt-5-codex, gpt-5-mini
Gemini CLI / AI Studio / Vertex	gemini-2.5-pro, gemini-2.5-flash, gemini-3-pro-preview
Claude Code / Antigravity	claude-sonnet-4-5-20250929, claude-opus-4-5-20251101

在常见客户端里配置 §

OpenAI 官方 SDK / LangChain §

from openai import OpenAI
client = OpenAI(
    base_url="http://你的服务器IP:8317/v1",
    api_key="你的api-key",
)
client.chat.completions.create(
    model="gpt-5",
    messages=[{"role":"user","content":"hi"}],
)

Cline / Continue / Cursor §

把 OpenAI provider 的 base URL 改成 http://你的服务器IP:8317/v1，model name 填 gpt-5 / claude-sonnet-4-5-20250929 等。

Claude Code CLI §

通过 Claude 协议路径：

export ANTHROPIC_BASE_URL=http://你的服务器IP:8317
export ANTHROPIC_API_KEY=你的api-key
claude  # 或者 anthropic 客户端

Codex CLI §

export CODEX_API_KEY=你的api-key
export CODEX_BASE_URL=http://你的服务器IP:8317
codex

具体环境变量名以各客户端文档为准，CPA 端不挑。

模型路由进阶 §

1. Prefix 路由 §

在 config.yaml 里给某个 key 设 prefix 后，请求 prefix/model-name 才会用这条凭据：

codex-api-key:
  - api-key: "sk-..."
    prefix: "team-a"
    base-url: "https://api.openai.com/v1"

客户端调用：model: "team-a/gpt-5"

2. 别名映射 §

codex-api-key:
  - api-key: "sk-..."
    models:
      - name: "gpt-5-codex"
        alias: "codex-latest"

客户端用 codex-latest，上游打到 gpt-5-codex。

3. 模型池（同 alias 多 backend） §

让 claude-opus-4.66 在多个上游间轮询：

openai-compatibility:
  - name: "openrouter"
    base-url: "https://openrouter.ai/api/v1"
    api-key-entries:
      - api-key: "sk-or-..."
    models:
      - name: "deepseek-v3.1"
        alias: "claude-opus-4.66"
      - name: "glm-5"
        alias: "claude-opus-4.66"

CPA 会在客户端模型列表中只展示一个 claude-opus-4.66，请求时轮询/失败转移。

速率与重试 §

CPA 自动处理：

• HTTP 403/408/500/502/503/504 自动重试（request-retry: 3）
• 凭据耗尽自动切下一个（max-retry-credentials）
• 失败凭据进入冷却期（disable-cooling: false 时）

你可以在管理面板的 “Usage” 标签里看每个凭据的请求量、错误率。

流式响应 §

OpenAI / Gemini / Claude 流式都支持：

curl -N http://你的服务器IP:8317/v1/chat/completions \
  -H "Authorization: Bearer 你的api-key" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-5","messages":[{"role":"user","content":"hi"}],"stream":true}'

下一步：08-config-reference.md 配置字段速查。