SurgeCode 快速接入指南

SurgeCode 提供与 OpenAI / Anthropic 完全兼容的 API 端点，只需把 base_url 指向 SurgeCode 并替换 API Key，即可在任意支持 OpenAI 协议的工具中接入。本文覆盖常用编码代理（Codex、Claude Code、Cursor、Cline、Pi、OpenClaw）的手动配置方式。

1. 准备工作

注册账号并进入控制台
在 API 密钥 页面创建一个密钥（如 sk-surge-xxxxxxxx）
记下你的接入地址：https://surgecode.org/v1

所有模型按实际 Token 用量计费，余额永不过期，无需订阅。

2. 一键配置（推荐）

无需手动编辑配置文件，执行下面一条命令即可自动配置 Codex、Claude Code、Cline、Pi：

curl -fsSL https://surgecode.org/quickstart.sh?lang=zh | bash -s -- sk-surge-xxxxxxxx

脚本会：

写入 Codex 配置（~/.codex/config.toml）并导出 OPENAI_API_KEY
写入 Claude Code 配置（~/.claude/settings.json 的 env 块）
写入 Cline 配置（VS Code settings.json）
写入 Pi 配置（~/.pi/agent/models.json）

所有文件写入前自动备份（.bak.时间戳），不会覆盖已有配置。也可指定工具与模型：

# 只配置 Codex 与 Claude Code
curl -fsSL https://surgecode.org/quickstart.sh?lang=zh | bash -s -- sk-surge-xxxxxxxx --codex --claude

# 自定义模型
curl -fsSL https://surgecode.org/quickstart.sh?lang=zh | bash -s -- sk-surge-xxxxxxxx --model claude-opus-5 --claude-model claude-opus-5

执行完成后重新打开终端使环境变量生效。建议先查看脚本内容再执行：

curl -fsSL https://surgecode.org/quickstart.sh?lang=zh | less

3. 用 curl 快速验证

配置任何工具前，先用 curl 确认端点与密钥可用：

curl -X POST https://surgecode.org/v1/chat/completions \
  -H "Authorization: Bearer sk-surge-xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.6-sol",
    "messages": [{"role": "user", "content": "你好"}]
  }'

返回包含 choices 字段的 JSON 即说明接入成功。若报 401，请检查密钥是否来自 SurgeCode 控制台。

4. Codex CLI

OpenAI Codex CLI 支持通过 ~/.codex/config.toml 指向自定义端点。

推荐方式——顶层 openai_base_url（新版 Codex 支持，取代已废弃的 OPENAI_BASE_URL 环境变量）：

# ~/.codex/config.toml
model = "gpt-5.6-sol"
openai_base_url = "https://surgecode.org/v1"

然后设置 API Key 环境变量并运行：

export OPENAI_API_KEY="sk-surge-xxxxxxxx"
codex

如果 openai_base_url 未生效（旧版本），改用自定义 provider 写法：
model = "gpt-5.6-sol"
model_provider = "surgecode"

[model_providers.surgecode]
name = "SurgeCode"
base_url = "https://surgecode.org/v1"
wire_api = "responses"
env_key = "OPENAI_API_KEY"

5. Claude Code

Claude Code 通过环境变量支持自定义网关。使用 ANTHROPIC_AUTH_TOKEN（而非 ANTHROPIC_API_KEY）作为认证凭据，因为自定义端点走 Authorization: Bearer 头：

export ANTHROPIC_BASE_URL="https://surgecode.org"
export ANTHROPIC_AUTH_TOKEN="sk-surge-xxxxxxxx"
export ANTHROPIC_MODEL="claude-sonnet-5"
claude

持久化配置（推荐写入 ~/.claude/settings.json）：

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://surgecode.org",
    "ANTHROPIC_AUTH_TOKEN": "sk-surge-xxxxxxxx",
    "ANTHROPIC_MODEL": "claude-sonnet-5",
    "ANTHROPIC_SMALL_FAST_MODEL": "claude-haiku-4-5"
  }
}

注意：ANTHROPIC_BASE_URL 指向根域（不含 /v1），Claude Code 会自动追加 /v1/messages。若同时设置了 ANTHROPIC_API_KEY，请先 unset 它，避免 401。

6. Cursor

Cursor 支持通过「覆盖 OpenAI Base URL」接入任意 OpenAI 兼容端点：

打开 Cursor 设置（Cmd+Shift+J）
进入 Models 页面
在 API Keys 区域填入你的 SurgeCode 密钥
勾选 Override OpenAI Base URL，填写 https://surgecode.org/v1
在 Model Names 中点击 + Add Model，添加 gpt-5.6-sol（或定价页中的其他模型 ID）
点击 Verify 验证连接

之后在聊天面板的模型下拉框中即可选择 SurgeCode 的模型。

注意：

Base URL 以 /v1 结尾（Cursor 会自动追加 /chat/completions），不要填完整路径。

Cursor 的 Agent 模式可能发送 Responses API 格式请求，若报错可先切换到 Ask 模式，或在网络设置中切换 HTTP/1.1。

Tab 自动补全与内联编辑不经过自定义端点，仍使用 Cursor 自身服务。

7. Cline

Cline（VS Code 扩展）支持「OpenAI Compatible」provider：

打开 Cline 面板，点击 ⚙️ 设置
API Provider 选择 OpenAI Compatible
Base URL 填写 https://surgecode.org/v1
API Key 填写你的 SurgeCode 密钥
Model ID 填写 gpt-5.6-sol（或定价页中的其他模型 ID）
点击 Verify 验证连接

也可以直接写入 VS Code 的 settings.json：

{
  "cline.apiProvider": "openai",
  "cline.openAiBaseUrl": "https://surgecode.org/v1",
  "cline.openAiApiKey": "sk-surge-xxxxxxxx",
  "cline.apiModelId": "gpt-5.6-sol"
}

Cline CLI 用户可使用 cline auth 命令：

cline auth -p openai -k sk-surge-xxxxxxxx -b https://surgecode.org/v1 -m gpt-5.6-sol

8. Pi

Pi 编码代理支持通过 ~/.pi/agent/models.json 注册自定义 provider（OpenAI 兼容协议）：

{
  "providers": {
    "surgecode": {
      "name": "SurgeCode",
      "baseUrl": "https://surgecode.org/v1",
      "apiKey": "$SURGECODE_API_KEY",
      "api": "openai-completions",
      "models": [
        {
          "id": "gpt-5.6-sol",
          "name": "GPT-5.6 Sol",
          "reasoning": true,
          "input": ["text"],
          "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 },
          "contextWindow": 128000,
          "maxTokens": 16384
        }
      ]
    }
  }
}

设置密钥并启动：

export SURGECODE_API_KEY="sk-surge-xxxxxxxx"
pi --provider surgecode --model surgecode/gpt-5.6-sol

9. OpenClaw

OpenClaw 在配置中通过 models.providers 声明自定义 provider：

{
  models: {
    providers: {
      surgecode: {
        baseUrl: "https://surgecode.org/v1",
        apiKey: "SURGECODE_API_KEY",
        api: "openai-completions",
        models: [
          {
            id: "gpt-5.6-sol",
            name: "GPT-5.6 Sol",
            reasoning: true,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 128000,
            maxTokens: 16384
          }
        ]
      }
    }
  }
}

写入 ~/.openclaw/agents/<agent>/models.json（或网关配置），然后：

export SURGECODE_API_KEY="sk-surge-xxxxxxxx"
openclaw models list --provider surgecode
openclaw models set surgecode/gpt-5.6-sol

10. OpenAI SDK 通用接入

任何使用 OpenAI SDK 的项目，只需修改 base_url 与 api_key：

from openai import OpenAI

client = OpenAI(
    base_url="https://surgecode.org/v1",
    api_key="sk-surge-xxxxxxxx",
)

resp = client.chat.completions.create(
    model="gpt-5.6-sol",
    messages=[{"role": "user", "content": "你好"}],
)
print(resp.choices[0].message.content)

兼容 Node.js、Python 等官方 SDK 及所有开源框架。模型列表与实时价格见定价页。

11. 常见问题

401 / 认证失败：确认 api_key 使用了 SurgeCode 控制台创建的密钥，而非其他平台密钥。
404 / 模型不存在：模型 ID 必须以定价页为准（如 gpt-5.6-sol、claude-sonnet-5）。
Claude Code 报 401：检查是否残留 ANTHROPIC_API_KEY，自定义端点应使用 ANTHROPIC_AUTH_TOKEN。
工具连不上端点：先运行第 3 节的 curl 命令，若 curl 成功而工具失败，通常是 Base URL 拼写或模型 ID 配置问题。
费用疑问：所有调用按 Token 实际用量计费，控制台可实时查看每次请求的 token、延迟与费用。