WinRouter
首页 Codex Desktop 设置 Claude Desktop 设置

接入文档

用 WinRouter 调用 GPT、Claude 和 gpt-image-2

本页介绍统一 Base URL、API 密钥、Codex Desktop 设置、Claude Desktop、Claude Code 和 CURL 调用。所有示例中的 sk-xxx 都需要替换成你自己的 WinRouter API 密钥

填写后，页面所有 sk-xxx 示例会自动替换；注意，Codex 和 Claude 使用 Key 不一样（后台可配置）。

Codex Desktop 设置

选择你的系统复制配置命令，或切换到手动配置查看 config.toml 内容。API Key 在右下角单独设置，用于登录 Codex。

MacOS 配置命令

Claude Desktop 设置

Claude Desktop 支持第三方 Provider / Gateway。启用开发者模式后，填写 WinRouter Gateway 地址和 API Key 即可通过 WinRouter 调用 Claude 模型。

配置步骤

  1. 安装并打开 Claude Desktop。
  2. macOS：点击顶部菜单中依次点击 Help → Troubleshooting → Enable Developer Mode，确认后让 Claude Desktop 重启。
  3. 重启后先不要登录，点击 Developer → Configure Third-Party Inference... 打开第三方 Provider 配置。
  4. 在 Connection 中选择 Gateway，填写 Gateway base URL 为 https://winrouter.ai/。
  5. 找到 Credential kind，选择 Static API Key，再在出现的 Gateway API key 中填入你在 WinRouter 的密钥。
  6. 设置 Gateway auth scheme 为 x-api-key，下拉点击 Test Model Discovery 按钮同步模型列表。
  7. 最后点击 Apply Changes 按钮保存配置后重启，即可正常使用。

如果 WinRouter 控制台展示了专门用于 Claude / Anthropic 的地址，请优先使用控制台展示的地址。

用途 配置值
Gateway base URL https://winrouter.ai/
Gateway API key sk-xxx
Connection Gateway
Credential kind Static API Key
Gateway auth scheme x-api-key

Claude Code 使用 Claude 模型

Claude Code 通过环境变量接入 WinRouter，设置 Base URL、Auth Token 和模型 ID 后即可调用 Claude 模型。

Claude Code 配置

  1. 设置 Claude Code 环境变量。
  2. Base URL 填写 https://winrouter.ai。
  3. Auth Token 填写你的 WinRouter API 密钥。
  4. 模型填写 claude-sonnet-4.6、claude-opus-4.8 或 claude-haiku-4.5。

请从已加载这些环境变量的终端启动 Claude Code，或重新打开终端后再运行。

环境变量示例
export ANTHROPIC_BASE_URL="https://winrouter.ai"
export ANTHROPIC_AUTH_TOKEN="sk-xxx"
export ANTHROPIC_MODEL="claude-sonnet-4.6"
export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1
export CLAUDE_CODE_ATTRIBUTION_HEADER=0
export MAX_CONSECUTIVE_AUTOCOMPACT_FAILURES=3

通用配置地址和 Key

WinRouter 提供 OpenAI 兼容接口、Claude Desktop Gateway 和 Claude Code 环境变量接入方式。不同客户端字段名可能不同，但核心配置只有 Base URL、Key 和模型 ID。

用途 配置值 说明
OpenAI Base URL https://winrouter.ai/v1 用于 GPT 文本模型、gpt-image-2 图片模型和 Claude messages CURL 调用。
Claude Code 环境变量 Base URL https://winrouter.ai 用于 Claude Code 的 ANTHROPIC_BASE_URL，不要带 /v1。
Claude Desktop Gateway base URL https://winrouter.ai 用于 Claude Desktop 的第三方 Provider / Gateway 配置。
API Key / Auth Token sk-xxx 在 WinRouter 控制台创建API 密钥，文档和脚本中的占位 Key 都必须替换。
常用 GPT 模型 ID gpt-5.5 / gpt-5.4 / gpt-5.3-codex 用于 OpenAI 兼容的 chat completions 接口。
常用 Claude 模型 ID claude-opus-4.8 / claude-sonnet-4.6 / claude-haiku-4.5 用于 Claude Code 和 Claude messages 调用。

如果某个客户端没有单独的 Base URL 设置项，通常可以通过环境变量或配置文件设置。具体字段名以客户端版本为准。

CURL 调用

GPT 和 Claude 都可以用 curl 调用。选择下面的标签查看对应协议和请求头。

GPT chat completions
curl https://winrouter.ai/v1/chat/completions \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "messages": [
      { "role": "user", "content": "用一句话介绍 WinRouter" }
    ]
  }'

使用 gpt-image-2 生成图片

图片生成使用 OpenAI 兼容的 images 接口。价格按实际图片尺寸计费，quality 不影响价格。

生成 2K 图片 
curl https://winrouter.ai/v1/images/generations \
  -H "Authorization: Bearer sk-xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-image-2",
    "prompt": "A clean product dashboard for an AI router",
    "size": "2K"
  }'

参数说明

  • model 固定为 gpt-image-2。
  • size 可选 1K、2K、4K。
  • quality 可省略；即使传入 low / medium / high，也不改变价格。
  • 如果省略 size，默认按 auto 处理，通常落到 2K 档。

常见问题

如果调用失败，优先检查 Base URL、API Key、模型 ID 和客户端是否支持自定义 API 地址。

WinRouter 的 Key 应该填在哪里？

在支持自定义 API Provider 的客户端中，将 Key 填到 API Key 字段；curl 中则放在 Authorization 或 x-api-key 请求头里。示例中的 sk-xxx 必须替换。

OpenAI 兼容和 Claude Code 配置有什么区别？

GPT、gpt-image-2 和 Claude messages CURL 使用 https://winrouter.ai/v1；Claude Code 的 ANTHROPIC_BASE_URL 使用 https://winrouter.ai，不带 /v1。

Claude 桌面端可以使用吗？

可以。Claude Desktop 启用 Developer Mode 后，在 Configure Third-Party Inference... 中选择 Gateway，填写 WinRouter Gateway base URL、Static API Key 和 x-api-key auth scheme，Test Model Discovery 后 Apply Changes 并重启即可。

Codex 设置后为什么没有生效？

Codex 桌面端通常需要重启后读取 config.toml。Claude Code 需要从已加载环境变量的终端启动。

通过接口访问时如何提高缓存命中、降低成本？

核心是保持可复用前缀稳定：同一任务使用固定 session_id / conversation_id，可通过 X-Session-Id 等 Header 透传；系统提示词、工具定义和项目背景放在请求前部，动态内容放在末尾。参考 OpenAI Prompt caching 和 Anthropic Prompt caching。

如何确认模型 ID 是否正确？

模型 ID 以首页定价表下方的小字为准，例如 gpt-5.5、gpt-5.3-codex、claude-sonnet-4.6、gpt-image-2。