dwgx/WindsurfAPIPublic

JavaScript · MIT · ★3,046

docs · releases · issues

把 Windsurf / Devin 的 100+ AI 模型（Claude、GPT、Gemini、DeepSeek、Kimi、GLM、SWE…）变成 OpenAI Chat / Responses / Anthropic / Gemini 四套标准 API。零 npm 运行时依赖。

历史账本 · 把 1387 次提交、196 个版本、82 个 PR、180 个 issue 摊开给你看：时间线主账 + 贡献者分析 + Git 树三形态（竖/横/环）+ 自伤与返工全记录 —— 打开可视化账本（纯原生渲染，零依赖）

           ·  English

没点 Star 和 Follow 的：严禁商业使用、转售、代部署、挂后台对外提供服务、包装成中转服务出售。 点了 Star 和 Follow 的：随便用，我睁一只眼闭一只眼。

代码本体按 MIT License 开源（见 LICENSE），上面这段是作者个人态度。

把 Windsurf（原 Codeium，现 Devin Desktop）的 AI 模型变成四套标准 API 同时兼容：

• POST /v1/chat/completions — OpenAI 兼容 任何 OpenAI SDK 直接用
• POST /v1/completions — OpenAI 旧 Completions（非流式；prompt 包成一条 user turn，流式请走 chat）
• POST /v1/responses — OpenAI Responses 兼容（另有 GET / DELETE /v1/responses/{id} 读取与删除已存响应，需带身份 header，见下）
• POST /v1/messages — Anthropic 兼容 Claude Code / Cline / Cursor 直接连
• POST /v1beta/models/* — Gemini 兼容 直接对接 Gemini SDK

100+ 模型：Claude 4.5/4.6/Opus 4.7/5 · GPT-5/5.1/5.2/5.4/5.5/5.6-Luna 全系 · Gemini 2.5/3.0/3.1 · Grok · Qwen · Kimi K2.x · GLM 4.7/5/5.1/5.2 · MiniMax · SWE 1.5/1.6/1.7/2 · Arena 等。零 npm 依赖 纯 Node.js。

_{关键词：Windsurf 逆向 · Devin 代理 · Claude Code 中转 · Cursor 镜像 · AI 中转 API · OpenAI 兼容接口 · 免费 Claude/GPT/Gemini · 大模型反代 · Codeium 逆向}

原理 · 5 分钟跑起来 · 客户端接入 · 环境开关 · 全部文档 · English

flowchart LR
    subgraph clients["你的客户端"]
        A["OpenAI SDK<br/>curl / 前端"]
        B["Claude Code<br/>Cline · Cursor"]
        C["Gemini SDK"]
    end

    subgraph gw["WindsurfAPI（本服务 · 端口 3003）"]
        direction TB
        R["协议翻译层<br/>OpenAI ↔ Anthropic ↔ Gemini"]
        P["账号池<br/>轮询 · 限流隔离 · 故障转移 · 熔断"]
        N["身份中和<br/>剥掉上游 Windsurf 身份"]
        R --- P
        R --- N
    end

    LS["Language Server<br/>（Windsurf 二进制）"]
    UP["Windsurf 云端<br/>server.self-serve.windsurf.com"]
    DC["Devin 云端<br/>（DEVIN_CONNECT 路径）"]

    A -- "/v1/chat/completions" --> R
    B -- "/v1/messages" --> R
    C -- "/v1beta/models/*" --> R
    R -- "gRPC" --> LS
    LS -- "HTTPS" --> UP
    R -. "HTTPS（可选直连）" .-> DC

    classDef gwStyle fill:#1f6feb22,stroke:#1f6feb,stroke-width:2px
    classDef upStyle fill:#8957e522,stroke:#8957e5
    class gw gwStyle
    class UP,DC upStyle

     ┌─────────────┐   /v1/chat/completions   ┌────────────┐
     │ OpenAI SDK  │ ──────────────────────→  │            │
     │ curl / 前端 │ ←──────────────────────  │            │
     └─────────────┘   OpenAI JSON + SSE      │ WindsurfAPI│
                                              │ Node.js    │      ┌──────────────┐       ┌─────────────────┐
     ┌─────────────┐   /v1/messages           │ (本服务)   │ gRPC │ Language     │ HTTPS │ Windsurf 云端   │
     │ Claude Code │ ──────────────────────→  │            │ ───→ │ Server (LS)  │ ────→ │ server.self-    │
     │ Cline       │ ←──────────────────────  │            │ ←─── │ (Windsurf    │ ←─── │ serve.windsurf  │
     │ Cursor      │   Anthropic SSE          │            │      │  binary)     │       │ .com            │
     └─────────────┘                          └────────────┘      └──────────────┘       └─────────────────┘
                                                    ↑
                                                账号池轮询
                                                速率限制隔离
                                                故障转移

它做了什么：

1. 一个 HTTP 服务（端口 3003）同时暴露 OpenAI 和 Anthropic 两套 API
2. 把请求翻译成 Windsurf 内部 gRPC 协议，通过本地 Language Server 发给 Windsurf 云
3. 维护账号池，自动轮询 + 速率限制 + 故障转移
4. 返回前把上游 Windsurf 身份剥掉，模型自称"我是 Claude Opus 4.6 由 Anthropic 开发"

模型本身不会操作文件 — 文件操作是 IDE Agent 客户端（Claude Code / Cline 等）在本地执行的：

 你 "帮我改 bug"                Claude Code                    WindsurfAPI               Windsurf Cloud
   │                                │                               │                          │
   │────────────────────────────→  │                               │                          │
   │                                │  POST /v1/messages            │                          │
   │                                │  messages + tools + system    │                          │
   │                                │ ─────────────────────────────→│ 打包成 Cascade 请求      │
   │                                │                               │ ──────────────────────→  │
   │                                │                               │                          │
   │                                │                               │               模型思考 → 返回
   │                                │                               │               tool_use(edit_file)
   │                                │                               │ ←──────────────────────  │
   │                                │ ←── Anthropic SSE ────────────│                          │
   │                                │   content_block=tool_use      │                          │
   │                                │                               │                          │
   │                                │ 本地执行 edit_file()          │                          │
   │                                │ (读写本地文件)                │                          │
   │                                │                               │                          │
   │                                │ 带 tool_result 再发一轮       │                          │
   │                                │ ─────────────────────────────→│ ──────────────────────→  │
   │                                │                                             ... (循环) ...
   │                                │                               │                          │
   │  ← 最终答案                    │                               │                          │

重点：WindsurfAPI 只负责传递 tool_use / tool_result，真正改文件的是客户端 CLI。

git clone https://github.com/dwgx/WindsurfAPI.git
cd WindsurfAPI
bash setup.sh          # 建目录 · 配权限 · 生成 .env
node src/index.js

Dashboard：http://你的IP:3003/dashboard

cp .env.example .env
# 空 API_KEY / DASHBOARD_PASSWORD 是 fail-closed（compose 默认 0.0.0.0，起来也是 401）。
# compose 默认 DEVIN_CONNECT=1，不跑 Language Server，不会自动下载 LS。
# 只有关掉 DEVIN_CONNECT、走 Cascade 时才会在缺二进制时尝试安装 LS。

docker compose up -d --build
docker compose logs -f

默认挂载：

• ./.docker-data/data：持久化 accounts.json、proxy.json、stats.json、runtime-config.json、model-access.json、logs/
• ./.docker-data/opt/windsurf：Language Server 二进制与数据目录
• ./.docker-data/tmp/windsurf-workspace：临时工作区

如果想改持久化目录，可在 .env 里设置 DATA_DIR。Docker 默认已设为 /data。

部署过之后要拉最新修复，一条命令搞定：

cd ~/WindsurfAPI && bash update.sh

update.sh 做了：git pull → 通过 install-ls.sh 更新 LS binary → 停 PM2 → kill 3003 端口残留 → 重启 → 健康检查。

如果你用的是我们的公网实例（skiapi.dev 之类），不用管，我们已经推过了。

git clone https://github.com/dwgx/WindsurfAPI.git
cd WindsurfAPI

# Language Server 二进制 —— 自动检测 Linux/macOS，一键下载 + chmod
bash install-ls.sh

# 下载链：WindsurfAPI release → 公开 LS mirror
#   https://github.com/dwgx/windsurf-ls-release/releases/latest/download
# → Exafunction/codeium fallback。需要私有镜像或回滚时可设置：
#   WINDSURFAPI_LS_RELEASE=https://github.com/<owner>/<repo>/releases/latest/download bash install-ls.sh

# 默认安装路径：
#   Linux x64:          /opt/windsurf/language_server_linux_x64
#   Linux arm64:        /opt/windsurf/language_server_linux_arm
#   macOS Apple Silicon: $HOME/.windsurf/language_server_macos_arm
#   macOS Intel:        $HOME/.windsurf/language_server_macos_x64

# 如果想用本地已下好的 binary：
#   bash install-ls.sh /path/to/language_server_linux_x64
# 或者指定 URL：
#   bash install-ls.sh --url https://example.com/language_server_linux_x64

# ⚠️ LS binary 版本偏旧 / 想换一个来源？
# 默认下载链已接入 dwgx/windsurf-ls-release 公开 mirror。
# 如果 mirror 暂未覆盖你的平台，仍可把 Windsurf 桌面端本体里的 LS binary 拷过来：
#
#   macOS:   "$HOME/Library/Application Support/Windsurf/resources/app/extensions/windsurf/bin/language_server_macos_arm"
#   Linux:   "$HOME/.windsurf/bin/language_server_linux_x64"
#            或  /opt/Windsurf/resources/app/extensions/windsurf/bin/language_server_linux_x64
#   Windows: %APPDATA%\Windsurf\bin\language_server_windows_x64.exe
#
#   # 从本地桌面端装：
#   bash install-ls.sh /path/to/language_server_linux_x64
#
# 注意：换 LS binary 不会改变 /v1/models 的内容。
# 模型目录是代理直连 HTTPS 拉的（GetCascadeModelConfigs / GetCliModelConfigs），
# 请求里的 ideVersion 写死在 src/windsurf-api.js，不从 binary 读 —— 所以目录只取决于
# 上游给这个账号授予了什么。看不到某个新模型，是上游还没放给该账号，不是本地文件旧了。

cat > .env << 'EOF'
PORT=3003
# Empty API_KEY is fail-closed (401) even on localhost.
# Local open access: WINDSURFAPI_ALLOW_UNAUTHENTICATED=1 and HOST=127.0.0.1
API_KEY=
DEFAULT_MODEL=claude-sonnet-4.6
MAX_TOKENS=8192
LOG_LEVEL=info
LS_BINARY_PATH=/opt/windsurf/language_server_linux_x64
LS_DATA_DIR=/opt/windsurf/data
LS_PORT=42100
# Empty DASHBOARD_PASSWORD is fail-closed. Local open panel: DASHBOARD_ALLOW_NO_AUTH=1
DASHBOARD_PASSWORD=
EOF

# macOS 本地部署时，使用 install-ls.sh 打印的 LS_BINARY_PATH，
# 并把 LS_DATA_DIR 设到用户可写目录，例如 /Users/you/.windsurf/data。

node src/index.js

服务跑起来之后要先加 Windsurf 账号才能用，三种方式：

方式 1 Dashboard 一键登录（推荐）

打开 http://你的IP:3003/dashboard → 登录取号 → 点 Google 登录 或 GitHub 登录（OAuth 弹窗）或直接填邮箱密码。所有方式都会自动入池。

方式 2 Token（任何登录方式都能用）

去 windsurf.com/show-auth-token 复制 Token：

curl -X POST http://localhost:3003/auth/login \
  -H "Content-Type: application/json" \
  -d '{"token": "你的token"}'

方式 3 批量

curl -X POST http://localhost:3003/auth/login \
  -H "Content-Type: application/json" \
  -d '{"accounts": [{"token": "t1"}, {"token": "t2"}]}'

from openai import OpenAI
client = OpenAI(base_url="http://你的IP:3003/v1", api_key="你设的API_KEY")
r = client.chat.completions.create(
    model="claude-sonnet-4.6",
    messages=[{"role": "user", "content": "你好"}]
)
print(r.choices[0].message.content)

export ANTHROPIC_BASE_URL=http://你的IP:3003
export ANTHROPIC_API_KEY=你设的API_KEY
claude                # 正常用 Claude Code 即可

# 裸 curl 测试
curl http://localhost:3003/v1/messages \
  -H "Authorization: Bearer 你的key" \
  -H "anthropic-version: 2023-06-01" \
  -d '{"model":"claude-opus-4.6","max_tokens":100,"messages":[{"role":"user","content":"你好"}]}'

Gemini 原生客户端不发 Authorization: Bearer，它用 x-goog-api-key 头或 ?key= 查询参数 —— 两种都收，所以官方 SDK 不用改代码就能连。

from google import genai
client = genai.Client(
    api_key="你设的API_KEY",
    http_options={"base_url": "http://你的IP:3003"},
)
r = client.models.generate_content(model="claude-sonnet-4.6", contents="你好")
print(r.text)

# 非流式
curl "http://localhost:3003/v1beta/models/claude-sonnet-4.6:generateContent" \
  -H "x-goog-api-key: 你的key" \
  -H 'content-type: application/json' \
  -d '{"contents":[{"role":"user","parts":[{"text":"你好"}]}]}'

# 流式（?alt=sse 才是 SSE，不带就是 JSON 数组分片）
curl -N "http://localhost:3003/v1beta/models/claude-sonnet-4.6:streamGenerateContent?alt=sse" \
  -H "x-goog-api-key: 你的key" \
  -H 'content-type: application/json' \
  -d '{"contents":[{"role":"user","parts":[{"text":"数到三"}]}]}'

/v1/responses 除了 POST，还有 GET /v1/responses/{id} 和 DELETE /v1/responses/{id}。 链式调用靠 previous_response_id，服务端替你保存上一轮 —— 这样第二轮不用重发历史。

# 第一轮：拿到 response id
curl http://localhost:3003/v1/responses \
  -H "Authorization: Bearer 你的key" \
  -H 'content-type: application/json' \
  -d '{"model":"claude-sonnet-4.6","input":"记住数字 42","store":true}'

# 第二轮：只发新问题，历史由服务端接上
curl http://localhost:3003/v1/responses \
  -H "Authorization: Bearer 你的key" \
  -H 'content-type: application/json' \
  -d '{"model":"claude-sonnet-4.6","input":"我让你记的数字是几?",
       "previous_response_id":"resp_把上一轮返回的id填这里","store":true}'

# 取回 / 删除
curl http://localhost:3003/v1/responses/resp_xxx -H "Authorization: Bearer 你的key"
curl -X DELETE http://localhost:3003/v1/responses/resp_xxx -H "Authorization: Bearer 你的key"

存储默认开（RESPONSE_STORE_ENABLED=0 关掉）。容量上限也可调： RESPONSE_STORE_TTL_MS（空闲超时,默认 1 小时）、RESPONSE_STORE_MAX_AGE_MS（绝对保留 上限,默认 24 小时）、RESPONSE_STORE_MAX（条数,默认 2000）、 RESPONSE_STORE_MAX_MESSAGES（单会话消息数,默认 400）、RESPONSE_STORE_MAX_BYTES （总字节预算,默认 128m,支持 b/k/kb/m/mb/g/gb）。

租户隔离靠的是 response id 的 90 bit 熵,不是客户端自称的作用域 —— 共享同一个 API key 时,两个调用方发相同的 user 会推导出逐字节相同的 callerKey,所以别把 id 当成除"难猜"以外的任何保证。

在客户端配置里 Custom OpenAI Compatible：

• Base URL: http://你的IP:3003/v1
• API Key: 你设的 API_KEY
• Model: 任选我们支持的模型

Cursor 用户注意：Cursor 客户端白名单会拦截含 claude 的模型名（请求根本不到后端）。用以下别名绕过：

在 Cursor 填	实际模型
opus-4.6	claude-opus-4.6
opus-4.6-thinking	claude-opus-4.6-thinking
opus-4.7	claude-opus-4-7-medium
sonnet-4.6	claude-sonnet-4.6
sonnet-4.5	claude-4.5-sonnet
haiku-4.5	claude-4.5-haiku
ws-opus	claude-opus-4.6
ws-sonnet	claude-sonnet-4.6

GPT / Gemini / DeepSeek 等不受 Cursor 白名单限制，直接填原名。

完整清单在 .env.example —— 上表只列常用的。 只存在于源码里、两处都没收录的开关见 docs/ENV-SWITCHES.md。

DEVIN_CONNECT 后端现在默认按真实 Devin wire 发送内联图片：

# 默认就是 10；仅在需要紧急回退时关闭
DEVIN_CONNECT_IMAGE_TAG=0

10 有两层独立证据：真实 Devin .proto 中 ChatMessagePrompt.images 是 repeated #10， ImageData 是 base64_data #1 / mime_type #2；真实 SWE-1.7 请求把图片直接挂在 source=USER 消息上，响应的 modelUid 仍是 swe-1-7，并正确识别了 macOS Dock、Sketch、 QQ 和 WPS。因此网关不再伪造 assistant read tool call、synthetic tool result 或顶层 read ToolDef，也不再按 swe-* 名字硬判定“无视觉”。

普通 user 图片保持在原 user 消息上；多图按 repeated #10 写进同一条消息。原生 tool result 里的图片保持 source=TOOL_RESULT，同时保留调用方的 tool_call_id #7。目录同步还会解码 ClientModelConfig.supports_images #5，并在上游明确给出 true/false 时把 supports_images 暴露到 /v1/models；字段缺失时保持未知，不伪造 false。上游 disabled #4 的模型不会进入 实时目录。

DEVIN_CONNECT_IMAGE_INNER_TAGS 仍可覆盖内部 base64,mime tag（默认 1,2），仅用于未来 wire 变更的应急校准。远程 https:// 图片 URL 仍不会由同步 wire builder 主动下载；请使用 data URL / base64，或显式开启 DEVIN_ACP_VISION=1 走本机 Devin CLI 的 ACP 视觉通道。

打开 http://你的IP:3003/dashboard：

主线 100+ 个静态模型 + Windsurf 雲端動態下發（mergeCloudModels 啟動時拉取最新）。Cascade 路径下，各账号云端 catalog 同步后，GET /v1/models 和 Dashboard 展示活跃账号目录的并集，路由则校验所选账号自己的目录；DEVIN_CONNECT 继续使用独立 selector catalog；静态完整列表仍可查看 GitHub Pages 模型清单（同步生成於 src/models.js）。

swe-1.6 / swe-1.6-fast / adaptive / arena-* 属于 special-agent 路径。direct Cascade 会报 unknown model UID / route 不通；默认不会假装可用。需要测试时显式开启 WINDSURFAPI_SPECIAL_AGENT_BACKEND=devin-cli，并安装/挂载 Devin CLI。当前 PoC 是 devin -p print 模式，默认拒绝 caller-local tools/media；ACP 工具桥接另做。

免费账号 entitled 模型主要是 gemini-2.5-flash、glm-4.7、glm-5 / 5.1、kimi-k2 / k2.5 / k2-6、qwen-3 等开源系列；Claude / GPT 全系 + Opus 系列要 Pro。具体每个账号的 entitled 清单看 dashboard。

工具调用稳定性（v2.0.82+ 实测）：Claude family 走 <tool_use> 协议最稳；GLM-4.7 / Kimi-K2.5 走 NLU 兜底 + 可选 retry 大部分 case 能调；GLM-5.1 在 cascade 后端不稳（经常空回复 textLen=0），proxy 救不动；GPT 在 cascade 协议层不传 tools[] schema 也救不全。Claude Code 调本地工具优先 claude-haiku-4.5 / claude-sonnet-4.6。

• 零 npm 依赖 全走 node:* 内置 · protobuf 手搓（src/proto.js）· 图片编解码 vendored（src/vendor/，BSD-3 jpeg-js + 自研纯-Node PNG 解码）· 下载即跑
• 账号池 + LS 池 每个独立 proxy 一个 LS 实例 不混用
• NO_TOOL 模式 planner_mode=3 关掉 Cascade 内置工具循环，避免 /tmp/windsurf-workspace/ 路径泄漏
• 三层 sanitize LS 内建工具结果过滤 · <tool_call> 文本解析 · 输出路径清洗
• 真实 token 计量 从 CortexStepMetadata.model_usage 抓 Cascade 真实 inputTokens / outputTokens / cacheRead / cacheWrite，prompt_tokens 含 cacheWrite

npm install -g pm2
pm2 start src/index.js --name windsurf-api
pm2 save && pm2 startup

不要用 pm2 restart（会出僵尸进程），用一键更新脚本 bash update.sh。

# Ubuntu
ufw allow 3003/tcp

# CentOS
firewall-cmd --add-port=3003/tcp --permanent && firewall-cmd --reload

云服务器记得去安全组开 3003。

按症状找,不用通读下面的问答。这是协议转换网关,所以排查的第一步永远是 分清是哪一层坏了 —— 客户端、本网关、还是上游。

flowchart TD
    S{"症状?"} --> A["请求根本没到<br/>连接被拒 / 超时"]
    S --> B["返回 401 / 403"]
    S --> C["有回复,但工具不调用"]
    S --> D["有回复,但内容不对<br/>丢上下文 / 混入思考过程"]
    S --> E["账号全挂<br/>rate-limited / unavailable"]

    A --> A1["1. 服务活着吗<br/>curl :3003/v1/models"]
    A1 --> A2["2. 防火墙放了 3003 吗<br/>见「防火墙」一节"]
    A2 --> A3["3. 超时别只调 .env<br/>看「context deadline」那条"]

    B --> B1["两层 key 别搞混:<br/>调用方 key ≠ 上游账号"]
    B1 --> B2["Gemini 客户端用<br/>x-goog-api-key 或 ?key="]

    C --> C1["先看日志里的 ToolRoute[...]<br/>它会列出被过滤/降级的原因"]
    C1 --> C2["再看是不是 server-side 工具<br/>翻译层会丢弃未实现的那类"]

    D --> D1["丢上下文 → 是否该用<br/>/v1/responses 链式"]
    D1 --> D2["混入思考 → 开 LEAK_TRACE<br/>抓边界日志"]

    E --> E1["先分清是账号被限<br/>还是 IP 级冷却"]
    E1 --> E2["看「All accounts<br/>temporarily rate-limited」那条"]

    classDef sym fill:#8957e522,stroke:#8957e5
    classDef act fill:#1f6feb22,stroke:#1f6feb
    class A,B,C,D,E sym
    class A1,A2,A3,B1,B2,C1,C2,D1,D2,E1,E2 act

两条最容易踩的：

排查请求链路时,发真实请求看响应,别只读代码 —— 这是协议转换网关,两层 key、四条出口路径,读代码容易推错。

Q: 登录报"邮箱或密码错误" A: 你是用 Google/GitHub 登录的 Windsurf 吧 那种账号没有密码。Dashboard 的登录取号面板现在直接支持 Google / GitHub OAuth 一键登录。

Q: 模型说"我无法操作文件系统" A: 这是 chat API，不是 IDE agent。要让模型真的改文件，用 Claude Code / Cline / Cursor / Aider 之类的客户端 CLI，把它们的 API base URL 指向本服务就行。模型出 tool_use，客户端本地执行，再把 tool_result 发回来。上面的图有详细流程。

Q: 上下文丢失 / 模型忘了前面说的 A: 多账号轮询不会丢上下文 — 每次请求都重新打包完整 history 发给 Cascade。真正的原因通常是中转层（new-api 等）没把完整 messages[] 透传过来。在 Dashboard 日志面板看 turns=N：如果多轮对话但 turns=1，就是中转层在你之前就把历史丢了。

Q: 长 prompt 超时 A: 已修。cold stall 检测按输入长度自适应，长输入最多给 90s。

Q: Claude Code 能用吗 A: 能。export ANTHROPIC_BASE_URL=http://你的API + export ANTHROPIC_API_KEY=你的key。/v1/messages 支持 system + tools + tool_use + tool_result + stream + multi-turn 全套，已实测通过。

Q: 免费账号能用什么模型 A: 主要是 gemini-2.5-flash、glm-4.7 / 5 / 5.1、kimi-k2 / k2.5 / k2-6、qwen-3 这些开源系列。Claude family + GPT 全系 + Opus / Max / Thinking 高阶模型要 Pro entitlement。具体每个账号的 entitled 清单 dashboard 里看 — model_not_entitled 错误返回的 available_in_pool 字段也会列出账号池能用的。

Q: 免费账号调工具稳吗 A: 看模型。Claude family <tool_use> 协议训练扎实最稳（free 账号若 entitled 也是优选）；GLM-4.7 / Kimi-K2.5 走 NLU 兜底 + WINDSURFAPI_NLU_RETRY=1 retry-with-correction 多数 case 能调；GLM-5.1 在 cascade 后端经常空回复 proxy 救不动；GPT 系列受 cascade 协议层限制（不传 OpenAI tools[] schema）也不稳。Claude Code / Cline / Codex 调本地文件 / 跑命令优先 claude-haiku-4.5 或 claude-sonnet-4.6。

Q: 客户端显示“没有调用工具”，怎么排查 A: 先看日志里的 ToolRoute[...]。它会列出客户端声明的工具、tool_choice 过滤后的有效工具、native bridge 映射/未映射工具、preamble 降级层级，以及 tool_choice_none / forced_tool_not_declared / preamble_compacted / native_bridge_* 等原因。/v1/messages 和 /v1/responses 的 server-side 工具（如 Anthropic advisor/code_execution，OpenAI file_search/mcp/computer_use）如果代理没有实现，会在翻译层丢弃；这类工具不是普通 function tool，不等于 WindsurfAPI 已经能替客户端执行。native bridge 也不是“本地 IDE 工具修复开关”：默认安全路径仍是 prompt/tool emulation，由客户端本地执行工具；native bridge 是让 Windsurf 远端 workspace 执行 Cascade 内置工具，只适合有模型/账号/API key gate 的小流量实验。

Q: 31 个 trial 账号一会儿就全 unavailable A: 八成是用了周限模型 — claude-opus-4-7-max / gpt-5.5-xhigh / claude-sonnet-4-7-thinking 这类高 reasoning effort 变体每个账号每周只有 5 次配额，31 号 × 5 次 ≈ 150 次就到顶。换 claude-sonnet-4.6 / claude-haiku-4.5 daily 配额比较宽松。docker logs windsurfapi-windsurf-api-1 | grep rate_limit 看每个账号的 cooldown 字段验证。

Q: All accounts temporarily rate-limited / IP-level cooldown 是不是代理坏了 A: 通常不是。Windsurf 上游会对同一出口 IP + 同一模型的密集请求施加 cooldown，多个账号绑在同一出口时会一起被限流。WindsurfAPI 会停止继续烧账号并返回 429 + Retry-After；v2.0.140 起这个等待时间会按上游 Resets in: 27m12s 这类真实值返回，而不是固定提示 30 秒。解决方向是降并发、换更宽松模型、给账号绑定不同出口 IP，或者等上游 cooldown 到期。

Q: free 账号是不是本地限制成 1 分钟 1 次 A: 不是。本地 free tier RPM 默认是 10/min。你看到的 1/min 或一段时间后恢复，通常是 Windsurf 上游 free-tier 动态限频或模型 entitlement 限制。Dashboard 里看账号状态和模型可用清单；请求无权限模型时错误里的 available_in_pool 会列出当前账号池能用的模型。

Q: context deadline exceeded / Client.Timeout 能靠调大 .env timeout 解决吗 A: 不能。长 thinking / 长输出在约 236-243 秒断流，是 Windsurf provider/Cascade 单次 stream 窗口。WindsurfAPI 会把它标成 upstream_deadline_exceeded / windsurf_provider_deadline，并丢弃半截 Cascade 复用轨迹，避免下一轮上下文错乱。实际规避只能拆任务、降低 reasoning/max output，或换更快模型。

特别感谢下面的朋友，他们提交过 PR 或系统性地审了代码，让这个项目变得更稳：

• @dd373156 — PR #1 修复 Pro 层级的模型合并逻辑：原本只看硬编码清单，云端动态拉回来的模型没进 tier 表，Pro 账号在 Cursor / Cherry Studio 里看不到新上线的模型。
• @colin1112a — PR #13 一次性审了 15 个安全 / 并发 / 资源管理 bug：XSS 转义、shell 注入、OOM 防护、auth 路由位置、gRPC 双回调、LS pool 竞态、HTTP/2 帧大小上限等。后续我们在这个基础上又加固了 JS-level escJsAttr、_pending 合并并发 ensureLs、LS 退出时释放 pooled session，并延伸修了 Antigravity 审计发现的 6 个问题。
• @baily-zhang — PR #36 + PR #45 Cascade reuse 的核心修复：stableTurns 指纹匹配 (#36) 解决了 0% 命中率；trajectory offset 增量拉取 (#45) 消除了多轮复用时的上下文膨胀。
• @aict666 — PR #44 修复 chat 调用后 inferTier 把 Pro/Trial 账号降级为 free 的 bug，保护了 GetUserStatus 设定的权威 tier。
• @smeinecke — PR #43 Dashboard 完整国际化：14 个 commit 覆盖中英文翻译、I18n 系统、check-i18n.js 校验工具。
• @you922 — PR #162 + PR #163 Sticky session 机制从零搭建（callerKey + modelKey → accountId 绑定）+ LS 崩溃指数退避自动重启。另外在 #164 提供了 SectionOverrideConfig 工具调用失效的源码级根因分析。
• @Fermiz — PR #181 Cascade 复用优化（单用户场景跳过轮询）+ HTTPS 代理层 + conversation-pool 大小可配置化。
• @linqichenggg — PR #175 Windows / macOS / Linux 三平台 LS 路径统一：二进制路径、数据目录、安装脚本全部对齐。
• @lauvww — PR #182 Dashboard 批量导入解析器重写：支持 JSON / CSV / 纯文本混合粘贴，自动检测分隔符。
• @ucloudnb666 — PR #184 Astraflow 第三方提供商接入。
• @datfooldive — PR #173 Dashboard UI 大扫除：统一组件风格、优化卡片布局和响应式适配。
• @The-five-stooges — PR #188 Sticky session 流式路径修复 + body.user 多用户隔离机制 + stickyNoFallback / stickyBindByUserOnly 双开关。
• @andya1lan — PR #192 update.sh 通过 install-ls.sh 更新 LS binary，统一 WindsurfAPI release / 公开 LS mirror / Exafunction 下载链，并修复 macOS grep -P 兼容性。
• @MatrixNeoKozak — PR #195 Dashboard API malformed JSON 现在返回 HTTP 400，不再用 200 包着 ok:false，让前端和自动化调用方能按状态码正确处理请求体格式错误。
• @brandonedley — PR #201 新增 GLM 5.2 和 Kimi K2.7 模型目录项，并同步 README / 英文 README / package 描述 / 模型 catalog 测试，给后续模型新增留下了代码、文档、测试一起更新的样板。
• @forrinzhao — PR #219 定位到 codex apply_patch 工具描述里的 FREEFORM tool, so do not wrap the patch in JSON. 会触发 Devin content policy(飞书 codex bot 全量被拦),live-bisect 7/7 确定性复现,并做了关键的双片段 A/B —— 只改一处仍拦、两处都改才过。这个发现顺带暴露出更深的结构缺陷:工具描述 preamble 注入在 neutralizeClientIdentity 之后,导致 native 路径上任何经由工具描述进来的触发词都绕过 a1-a6 整条防线。落地版把中和移到 preamble 注入之后,并把两条改写做成 (a7) 规则进既有序列(复用主开关与测试体系),因此覆盖所有客户端、所有触发词。另采纳其 responses.js 修复:Codex 发的 input item 是裸 {role, content} 不带 type:'message',此前被静默丢弃导致上游收到空 messages → UPSTREAM_INTERNAL。
• @warelik — PR #224 #225 #226 #227 #228 #229 一轮六连,覆盖账号池、限流、身份中和、协议规范四个子系统。429 reset window 双链根因:上游给的 3h 重置窗口在传输层被丢(只解构 {code, message}),且 model-scoped 冷却对 getApiKey(modelKey=null) 的池选择结构上不可见 —— 两条只修一条都毫无效果,刚被 429 的账号几秒内被重选、一路撞到硬封(#224)。客户端断连不再当成账号故障:统一识别 abort(兼容 undici 与 AbortController 两种形态),流式/非流式全部退出路径不再罚 error budget、不再 failover 烧配额、不再往死 socket 写(#225)。Grok CLI 的 You are Grok … released by xAI self-ID 触发 content policy,补进 a1-a5 同族规则并整块剥离 <executing_actions_with_care>(#227)。thinking 块 signature: "" 改为省略,修严格客户端拒收(#228)。Responses usage 补齐 input/output_tokens_details,与 DEVIN_CONNECT 缓存 wire tag 校准正好凑成一条链的两半(#229)。另有 600 行零依赖的 pair-chain 会话连续性模块,从对话自身已完成的请求/响应对推导稳定 session_id,默认关、开关闭合时字节等价(#226)。
• @warelik — PR #216 + PR #215 中和上游 MCP-gate：server.codeium.com 对工具描述做指纹匹配，Cursor 21 个工具里 8 个被 permission_denied 拒掉；把 native #10 ToolDef 顶层描述换成工具名 + 递归剥参数 schema 的描述注解（保留结构和名叫 description 的参数），再把描述-only preamble 注入 system prompt 补回选工具上下文，21/21 全过（#216）。另修 Node 20+ IPv6 Happy Eyeballs 导致的 ETIMEDOUT：关掉 autoSelectFamily + 本地 HTTP/2 连接改用 127.0.0.1（#215）。

想加入这份名单？欢迎提 issue 或 pull request。Dashboard 左侧的"致谢"面板是更完整的一份：它从 contributors.json 渲染,当前 27 位贡献者、53 条记录,每条还带分级与机制说明；上面这份名单是其中人工挑选的一部分。

MIT License. See LICENSE.

发布流程会自动推 Docker 镜像和 GitHub Release。别把 token、API key、cookie、上游账号凭据 写进 issue、PR、日志或提交的配置文件里。 如果报告问题必须带上鉴权信息，只贴脱敏后的元数据 和复现步骤。

对应的英文段见 README.en.md。

Star History · 点击查看完整星图