教程

Windsurf 接入 CCSub 中转配置教程：API Key 与 Claude 模型选择

教程2026-09-15·9 分钟阅读

Windsurf 是不少团队在用的 AI 编辑器，但它默认只连自家模型服务，想换成中转线路需要手动改配置。这篇教程把「Windsurf 接入 CCSub」的完整流程拆开讲：从创建 API Key、填写 Base URL，到挑选 Claude 模型、跑通第一次对话，最后给一份连接失败时能逐条对照的自检清单。

开始前请确认两件事：你已经在 ccsub.xyz 注册账号并完成充值，账号里至少有一个可用的 API Key。如果这两步还没做，建议先看站内文档的「注册与充值」和「安装配置」两篇。

一、在 CCSub 创建 API Key

Windsurf 走的是 OpenAI 兼容协议，所以你只需要一个通用的 CCSub 密钥。

  1. 登录 CCSub 控制台，进入 API 密钥管理页面。
  2. 点击创建密钥，给它起一个能认出用途的名字，例如 windsurf-editor。
  3. 创建完成后立即复制密钥，格式形如 sk-你的CCSub密钥。多数面板只在创建时完整显示一次。
  4. 如果面板支持权限或额度设置，按团队需要限制即可。权限过窄（例如只放行了某一类模型）是后续最容易踩的坑，遇到 model_unavailable 时优先回来检查这一项。

同一个密钥可以在多个客户端复用，不必每个编辑器建一个。但如果你想把 Windsurf 的用量和 Claude Code、Codex 的用量分开看，分开建密钥会更清楚。

二、确认 Base URL 和端点

CCSub 对外提供两套协议入口，Windsurf 用的是其中的 OpenAI 兼容入口：

  • OpenAI 兼容 Base URL：https://ccsub.xyz/v1
  • 对话补全端点：https://ccsub.xyz/v1/chat/completions
  • 模型列表端点：https://ccsub.xyz/v1/models

另外两个入口是给别的客户端准备的，Windsurf 里不要填错：https://ccsub.xyz/api 是 Anthropic 原生协议入口，供 Claude Code 这类客户端自动请求 /v1/messages；https://ccsub.xyz/openai 是 Codex 的原生入口，配合 wire_api = responses，客户端会自动请求 /responses。这两套都不是 Windsurf 要用的。

一个高频错误：把 Base URL 写成 https://ccsub.xyz 再加路径，或者末尾多带一个斜杠写成 https://ccsub.xyz/v1/。不同客户端对斜杠的拼接处理不一致，可能拼出 /v1//chat/completions 这种地址，表现为 404 或 connect_error。建议严格照抄 https://ccsub.xyz/v1。

三、在 Windsurf 中填写自定义模型配置

Windsurf 支持接入自定义的 OpenAI 兼容服务，入口通常在你的账号或设置面板里的模型配置区域。不同版本界面文案可能略有差异，认准这几个字段即可：

  1. 打开 Windsurf 设置，找到模型 / Provider 配置区域，选择「自定义」或「OpenAI 兼容」类型的 Provider。
  2. API Key：粘贴第一步复制的 sk-你的CCSub密钥。
  3. Base URL / API Base：填写 https://ccsub.xyz/v1。
  4. Model ID：从下一节的模型列表里挑一个，原样填写，不要写成显示名称。
  5. 保存后新开一个对话窗口，发一句「你好，用一句话介绍你自己」做连通性测试。

部分版本还要求你选择请求路径是 /chat/completions 还是 /responses。Windsurf 走 OpenAI 兼容协议时选前者，完整地址就是 https://ccsub.xyz/v1/chat/completions。

如果你需要写进配置文件而不是界面，结构大致如下（字段名以你的版本为准）：

{
  "provider": "openai-compatible",
  "baseUrl": "https://ccsub.xyz/v1",
  "apiKey": "sk-你的CCSub密钥",
  "model": "claude-sonnet-4-6"
}

四、可用模型怎么查、怎么选

不要凭记忆猜模型 ID。CCSub 的可用模型以 GET https://ccsub.xyz/v1/models 的返回为准，你会看到类似 claude-opus-4-8 这样的小写连字符 ID。

Windsurf 里常用的是 Claude 系列，按任务复杂度分档选择：

  • 日常改代码、写单测、解释报错：claude-sonnet-4-6（Claude Sonnet 4.6）或 claude-sonnet-5。响应快，成本可控。
  • 复杂重构、跨文件推理、长链路调试：claude-opus-4-8（Claude Opus 4.8）。能力更强，单价也更高。
  • 轻量补全、格式转换、批量小任务：claude-haiku-4-5（Claude Haiku 4.5）。
  • 需要长期维护的固定版本：带日期后缀的 ID，例如 claude-haiku-4-5-20251001。

同系列通常还保留了 claude-opus-4-7、claude-opus-4-6、claude-sonnet-4-5 等较早版本，用于兼容已有项目的固定调用。如果某次请求返回 model_unavailable，说明这个 ID 当前不可调用，换一个再试，而不是反复重试同一个。

注意：模型 ID 区分大小写和连字符位置。claude-sonnet-4.6、Claude-Sonnet-4-6、claude_sonnet_4_6 都是错误写法，会直接报模型不存在。

五、成本与充值提醒

Windsurf 的消耗取决于你让它读多少上下文。索引整个仓库后提问，输入 token 会明显放大，而 CCSub 的计费是输入、输出分别计价，缓存读取通常更便宜。几条实际建议：

  • 先用 Sonnet 系列跑通流程，确认账号和额度和预期一致，再切 Opus 系列做重活。
  • 控制单次提问引用的文件范围，避免把无关目录一起塞进上下文。
  • 定期在控制台看 Token 明细，Claude 系模型输出单价通常高于输入，长回答比长提问更贵。
  • 充值按实际用量来，别一次性充太多。团队共用时更要注意密钥被多端同时调用。

价格以 CCSub 控制台和文档的模型定价分组为准，模型上下架会调整，不要以本文写死的心算数字为准。

六、首次连接失败的快速自检清单

按顺序逐条排除，绝大多数问题在前三条就能定位。

  1. Base URL 末尾斜杠：确认是 https://ccsub.xyz/v1，不是 https://ccsub.xyz/v1/，也不是漏了 /v1 的裸域名。
  2. 模型 ID 拼写：从 /v1/models 返回里复制粘贴，检查大小写、连字符、有没有把显示名称当成 ID。
  3. Key 权限与状态：确认密钥没被删除、没被限权、账户余额足够。权限过窄会导致特定模型不可用。
  4. 协议入口是否搞混：Windsurf 用 OpenAI 兼容入口；如果你误填了 https://ccsub.xyz/api 或 https://ccsub.xyz/openai，会出现 404 或格式错误。
  5. 网络与代理：本地代理、公司防火墙、证书拦截都可能导致 connect_error。先临时直连试一次，排除代理因素。
  6. 账号余额：余额不足时表现为请求被拒或空响应，回控制台确认一下。
  7. 客户端版本：过旧的 Windsurf 可能不支持自定义 Provider，升级到较新版本再试。

常见报错和对应方向：

  • connect_error：网络、代理、Base URL 写法问题，先核对地址再查网络。
  • empty_response：请求发出但没拿到内容，多为参数或上下文超限，试着缩短提问或换模型。
  • upstream_unavailable：上游临时波动，等几十秒重试一次，不要连续猛刷。
  • model_unavailable：模型 ID 不可用，换一个 ID 重试。

更系统的排查路径可以对照站内的「故障排查」文档，那里有按症状整理的速查表。

七、跑通之后做什么

第一次对话正常返回后，建议立刻做三件事：把当前配置截图或记下来，方便换机器时复现；在 Windsurf 里固定一个默认模型，避免每次手动切；把密钥和 Base URL 分开记录，密钥泄露时只需在 CCSub 控制台吊销重建，不用改所有客户端的地址。

接下来可以继续看「入门使用手册」了解提问技巧和 Token 明细的读法，或者「API 参数与推理能力」了解 Chat、Responses、Messages 三套接口各自支持的参数范围。如果你的团队同时用 Claude Code 或 Codex，那两个客户端要走 https://ccsub.xyz/api 和 https://ccsub.xyz/openai，别和 Windsurf 的配置混在一起。

CCSub API 调用方法

如果你使用 OpenAI 兼容客户端，把 Base URL 设置为 https://ccsub.xyz/v1，API Key 使用控制台创建的 sk-你的CCSub密钥。

export OPENAI_BASE_URL=https://ccsub.xyz/v1
export OPENAI_API_KEY=sk-你的CCSub密钥

Codex 请使用原生 Responses 专用地址。先设置密钥：

export CCSUB_API_KEY=sk-你的CCSub密钥

再在 ~/.codex/config.toml 配置自定义 provider：

model = "gpt-5.6-sol"
model_provider = "ccsub"
[model_providers.ccsub]
name = "CCSub"
base_url = "https://ccsub.xyz/openai"
env_key = "CCSUB_API_KEY"
wire_api = "responses"

Claude Code 使用专用 Messages Base URL：

export ANTHROPIC_BASE_URL=https://ccsub.xyz/api
export ANTHROPIC_AUTH_TOKEN=sk-你的CCSub密钥

需要确认当前可用模型时，可以请求 GET https://ccsub.xyz/v1/models。正式长任务前，建议先用短请求验证 Key、余额和模型是否正常。

读完想动手试试？3 分钟接入 CCSub。

立即注册返回博客
← 全部文章