集成与最佳实践

OpenAI SDK

所有 OpenAI 官方 SDK 都开箱即用，只改两行：


from openai import OpenAI
client = OpenAI(
    base_url="http://localhost:8000/v1",
    api_key="stk-live-...",
)


import OpenAI from "openai";
const client = new OpenAI({
  baseURL: "http://localhost:8000/v1",
  apiKey: "stk-live-...",
});

LangChain


from langchain_openai import ChatOpenAI
 
llm = ChatOpenAI(
    base_url="http://localhost:8000/v1",
    api_key="stk-live-...",
    model="deepseek/deepseek-chat",
)
print(llm.invoke("hello").content)

Cursor / Cline / Continue / Aider

所有这些 IDE / Coding Agent 都支持「OpenAI-compatible 自定义端点」配置项，填两个字段即可：

Cursor: Settings → Models → OpenAI API Key + Override OpenAI Base URL。
Cline（VS Code）: Settings → API Provider → OpenAI Compatible。
Continue: 编辑 ~/.continue/config.json，添加 provider openai，apiBase 指向 Smartoken。
Aider: 命令行加 --openai-api-base http://localhost:8000/v1 --openai-api-key stk-live-...。

这些工具通常会发自己默认的 model 名（如 gpt-4o）。建议在管理后台把那个 slug 加为别名，指向你实际想用的模型（如 deepseek/deepseek-chat）。

Codex / Responses API 客户端

OpenAI Codex CLI、Cursor 的部分模式、以及 Agents SDK 用的是 Responses API（/v1/responses，input 列表 + instructions 风格），而不是经典的 chat completions。Smartoken 同样支持，模型只要绑了 wire_api=responses 的渠道就行（包括 OAuth 中继账户，例如 ChatGPT Plus 订阅）。

Codex CLI：编辑 ~/.codex/config.toml：


model = "openai/gpt-5.4-mini"           # 你在 Smartoken 注册的模型 slug
model_provider = "Smartoken"
 
[model_providers.Smartoken]
name = "Smartoken"
base_url = "http://localhost:8000/v1"   # 生产替换为公网地址
wire_api = "responses"
env_key = "OPENAI_API_KEY"              # Codex 会读这个环境变量

然后 export OPENAI_API_KEY=stk-live-... 启动 codex 即可。不要加 requires_openai_auth = true —— 那会让 Codex 拿 ChatGPT 登录 OAuth 当 token 发给 Smartoken，被拒为 invalid relay key。

如果客户端只会说经典 chat 协议，但你想让它跑在一个 responses 渠道上（比如 ChatGPT Plus 订阅），不用改客户端 —— Smartoken 会自动把 messages 翻译成 input + instructions 发给上游 /responses，再把回应翻译回 chat 形态。同一个模型 slug 同时挂 chat 和 responses 渠道也没问题，按客户端的请求路径分发。

Claude Code

Claude Code 走 Anthropic Messages API（非 OpenAI 协议），目前 Smartoken 不直接支持。变通方案：用 litellm、claude-bridge 这类协议转换 proxy 把 Anthropic 请求转成 OpenAI 请求再发给 Smartoken。原生 Anthropic 兼容端点在 Roadmap 上。

流式输出

加 stream=true 即可，SSE 协议与 OpenAI 完全一致：


stream = client.chat.completions.create(
    model="deepseek/deepseek-chat",
    messages=[{"role": "user", "content": "讲个笑话"}],
    stream=True,
)
for chunk in stream:
    delta = chunk.choices[0].delta.content
    if delta:
        print(delta, end="", flush=True)

Smartoken 会在尾部插入 usage 块以保证计费精确，普通客户端会自动忽略；只要你的客户端循环到 [DONE] 都正常。

错误处理与重试

网关已经做了上游级别的自动 failover，客户端不必再加重试逻辑，否则可能放大故障。你只需正常处理 4xx / 5xx：

4xx：业务错误（参数不对、余额不足、密钥失效等），不要重试。
429：达到了模型限流，等 Retry-After 头指明的秒数再试。
503：所有上游渠道都挂了；过几秒重试一次，配合监控告警。
5xx 其它：极少见，可尝试一次重试。