SSOW
文档/CC Switch

CC Switch 接入 SSOW 中转服务

学习如何在 CC Switch 中配置 SSOW 中转服务，使用 GPT 和 Claude 系列模型，实现供应商管理。

实时同步GET /v1/models点击模型名称即可复制

SSOW 支持的模型清单

共 21 个 模型，覆盖 OpenAI GPT 与 Google Gemini / Nano Banana 系列。统一通过 /v1 兼容接口调用。

OpenAI · GPT 系列

共 11 个模型

适用于 Codex、Cursor、Cline、Cherry Studio 等 OpenAI 协议客户端

对话与推理

通用对话、推理、长上下文

编程专用

Codex 系列，代码生成与重构

图像生成

文生图、图像编辑

Google · Gemini / Nano Banana 系列

共 10 个模型

适用于 Gemini、图像生成与 Google 兼容模型调用场景

Gemini 对话与推理

Google Gemini 系列，通用对话与多模态推理

Nano Banana 图像生成

图像生成、图片编辑与视觉创作

模型列表已按当前支持的 OpenAI GPT 和 Google Gemini / Nano Banana 更新。点击模型名称即可复制 model id。

快速开始

5 分钟完成基础配置

添加供应商

配置 SSOW 中转服务

用量统计

查看 API 使用情况

CC Switch 接入 SSOWv3.13.0

CC Switch 是一个跨平台桌面工具，专门用来管理 Claude Code、Codex、OpenCode、OpenClaw 等 AI 编程 CLI 的 API 端点配置。一键切换不同供应商，不用反复改环境变量。

本文档讲清楚一件事：怎么在 CC Switch 里把 SSOW（https://token.ssow.org）配进去，然后让 Claude Code 等工具走 SSOW 中转。

为什么要用 CC Switch

  • 同时持有官方订阅 + SSOW 中转，按需切换
  • 多个 SSOW token（个人 / 团队 / 测试）独立管理
  • 不用每次手改 ~/.zshrc，UI 点一下就生效

一键切换

GUI 点击切换 Claude Code 后端，新会话立即生效

多账号管理

官方、SSOW、自建中转并存，互不干扰

用量监控

查看每个供应商的调用量和余额

安装

支持 Windows 10+ 和 macOS 11+，包含 Apple Silicon 原生构建。

macOS

Terminalbash
# 推荐：Homebrew
brew install --cask cc-switch

# 或下载 DMG
# https://github.com/farion1231/cc-switch/releases

Windows

PowerShellpowershell
# winget
winget install farion1231.cc-switch

# 或 Scoop
scoop bucket add extras
scoop install cc-switch

界面概览

首次启动看到的就是供应商管理面板。每张卡片代表一个供应商配置，激活后该应用（如 Claude Code）就走对应的端点。

CC Switch 主界面
供应商管理视图：左侧应用切换，中间供应商卡片
1

顶部应用切换

Claude Code、Codex、OpenCode、OpenClaw 各有独立配置区，互不影响。
2

供应商卡片

高亮边框 = 当前激活。双击卡片可立即激活；右键有编辑、复制、删除等操作。
3

右上角动作区

「+ 添加供应商」、设置、用量统计入口。

三步接入 SSOW

以 Claude Code 为例。Codex / OpenCode 流程一致，只是顶部应用切到对应 tab。

1

切到 Claude Code 应用

顶部应用切换器选「Claude Code」，确保下面显示的是 Claude Code 的供应商列表。
2

添加 SSOW 供应商

右上角「+ 添加供应商」，类型选「Anthropic 兼容」（CC Switch 内置 SSOW 预设可直接选用）。填入：
供应商配置text
名称       SSOW
Base URL  https://token.ssow.org
API Key   sk-xxxx...   # 从 https://token.ssow.org 后台「API 密钥」复制
3

双击卡片激活

激活后 CC Switch 会写入 ANTHROPIC_BASE_URL 和 ANTHROPIC_API_KEY。新开一个终端跑 claude，就走 SSOW 了。

已运行的终端不会自动更新

CC Switch 修改的是系统/用户级环境变量。已经打开的终端会话需要重启才会读到新值。

个性化配置

常用选项

选项说明建议
开机自启登录后台运行，方便系统托盘随时切换开
切换后通知切换供应商时弹系统通知开
主题浅色 / 深色 / 跟随系统跟随系统
语言中 / 英 / 日 / 繁中跟随系统

配置文件位置

配置目录bash
# macOS
~/Library/Application Support/cc-switch/

# Windows
%APPDATA%\cc-switch\

API key 在本地用系统钥匙串（macOS Keychain / Windows Credential Manager）加密存储，不走云端。

配置 SSOW 供应商

添加供应商配置界面
添加供应商对话框

必填字段

字段值
名称SSOW（任意名字，能区分就行）
类型Anthropic 兼容（用于 Claude Code）
Base URLhttps://token.ssow.org
API Keysk-xxx，从 SSOW 后台获取

OpenAI 兼容应用（Codex 等）

切到 Codex tab 后，类型选「OpenAI 兼容」，Base URL 填 https://token.ssow.org/v1。注意结尾的 /v1。

OpenAI 兼容配置（Codex 用）json
{
  "name": "SSOW",
  "type": "openai-compatible",
  "base_url": "https://token.ssow.org/v1",
  "api_key": "sk-xxx",
  "models": [
    "gpt-4o",
    "gpt-4-turbo",
    "claude-3-5-sonnet-20241022",
    "claude-3-opus-20240229"
  ]
}

多 token 负载均衡

有多个 SSOW token（比如个人 + 团队额度）时，可以建一个「统一供应商」把它们组合起来：

统一供应商json
{
  "name": "SSOW 池",
  "type": "unified",
  "base_url": "https://token.ssow.org",
  "keys": [
    { "key": "sk-personal-xxx", "weight": 1 },
    { "key": "sk-team-xxx",     "weight": 2 }
  ],
  "strategy": "weighted-round-robin"
}

切换供应商

三种切换方式

方式操作适用场景
主界面双击双击卡片日常切换
系统托盘右键托盘图标 → 选择供应商不打开主窗口
快捷键Cmd/Ctrl + 1~9高频切换

切换后是怎么生效的

CC Switch 会更新对应应用的环境变量：

环境变量变化bash
# 切到 SSOW 后，新终端里会看到
ANTHROPIC_BASE_URL=https://token.ssow.org
ANTHROPIC_API_KEY=sk-xxx

# 切回官方后
ANTHROPIC_BASE_URL=（取消设置）
ANTHROPIC_API_KEY=sk-ant-xxx

重启终端

已经打开的终端不会自动加载新值。切换供应商后，请新开一个终端窗口再启动 Claude Code。

编辑供应商

右键卡片 → 编辑，或者点击卡片右上角的铅笔图标。

什么时候要编辑

  • 更换 SSOW API key（旧 key 撤销后）
  • 调整模型列表（SSOW 上线了新模型）
  • 修改超时时间（默认 60s，复杂任务可调大）

编辑当前激活的供应商

修改会立即生效。如果改了 Base URL 或 API Key，CC Switch 会提示你「重启正在使用的 CLI」。

排序与复制

排序

长按卡片拖动调整顺序。排序影响 Cmd+1~9 快捷键的对应关系——第一个卡片就是 Cmd+1。

复制

右键 → 复制。常用场景：基于现有 SSOW 配置，建一个仅用于测试的副本（换个 token），不影响日常使用。

复制时记得换 key

复制会连同 API Key 一起带过来。请编辑副本，换成对应用途的 key。

用量查询

在卡片上直接看到 SSOW 余额，不用切到浏览器。

支持的查询源

供应商类型查询能力展示内容
SSOW 中转支持余额（USD）、本月已用 token
Anthropic 官方订阅支持剩余消息数、重置日期
官方 API支持本月用量、月度上限

启用查询

编辑供应商 → 「用量查询」标签 → 勾选「启用」，刷新间隔默认 5 分钟。

用量统计

右上角「统计」按钮，查看跨供应商、跨应用的调用明细。

能看到什么

  • 按供应商：SSOW / 官方 / 自建中转各用了多少
  • 按模型：Sonnet / Opus / Haiku 占比
  • 按应用：Claude Code 比 Codex 用得多还是少
  • 按时间：日 / 周 / 月趋势

对账小窍门

CC Switch 本地统计仅供参考，最终账单以 SSOW 后台「用量统计」为准。两边数据应基本一致，差异 1～2% 是正常的（缓存命中等）。

模型检查

配好 SSOW 后，点击卡片上的「测试」按钮，CC Switch 会跑一遍连通性检查：

检测项失败时怎么办
连接 Base URL检查网络、防火墙、代理设置
API Key 认证去 SSOW 后台确认 key 有效
拉取模型列表确认账户有调用权限和余额
流式响应（SSE）检查代理是否拦截长连接
首 token 延迟正常应在 2 秒内

什么时候跑测试

新建供应商后、切换网络环境后、报错排查时。测试只发一次极小的请求（10 token 以内），消耗可忽略。

相关资源

SSOW 控制台

管理 API 密钥、查看用量、充值

下载 CC Switch

获取最新版本的安装包

CC Switch GitHub

源码、Issue 和官方用户手册

文档/Cherry Studio

Cherry Studio 接入 SSOW 中转服务

了解如何在 Cherry Studio 中接入 SSOW 中转服务，配置模型参数，使用 GPT 和 Claude 系列模型。

实时同步GET /v1/models点击模型名称即可复制

SSOW 支持的模型清单

共 21 个 模型，覆盖 OpenAI GPT 与 Google Gemini / Nano Banana 系列。统一通过 /v1 兼容接口调用。

OpenAI · GPT 系列

共 11 个模型

适用于 Codex、Cursor、Cline、Cherry Studio 等 OpenAI 协议客户端

对话与推理

通用对话、推理、长上下文

编程专用

Codex 系列，代码生成与重构

图像生成

文生图、图像编辑

Google · Gemini / Nano Banana 系列

共 10 个模型

适用于 Gemini、图像生成与 Google 兼容模型调用场景

Gemini 对话与推理

Google Gemini 系列，通用对话与多模态推理

Nano Banana 图像生成

图像生成、图片编辑与视觉创作

模型列表已按当前支持的 OpenAI GPT 和 Google Gemini / Nano Banana 更新。点击模型名称即可复制 model id。

初始设置

首次使用配置指南

配置 SSOW

接入 SSOW 中转服务

提示词模板

创建高效对话模板

Cherry Studio 接入 SSOW最新

Cherry Studio 是一款开源的 AI 对话桌面客户端，OpenAI / Anthropic 兼容的 API 都能接。本文教你怎么把 SSOW（https://token.ssow.org）配进去，让 Cherry Studio 的对话窗口走 SSOW，按 token 计费用 GPT 和 Claude。

适合谁

  • 不想为多个 AI 服务分别开订阅，希望一个 token 同时调 GPT 和 Claude
  • 需要一个本地客户端管理对话历史，不愿意把数据留在 ChatGPT / Claude 网页
  • 想在不同模型之间快速切换对比效果

GPT + Claude 一站式

一个 SSOW token 同时调 OpenAI 和 Anthropic 全系列模型

本地存储对话

对话数据完全保存在本地，SSOW 不留对话内容

多模型对比

同一问题并排发给多个模型，看谁答得好

提示词模板

内置模板库 + 自定义助手，快速启动专项任务

Cherry Studio 主界面
Cherry Studio 对话界面

三步上手

通常 1～2 分钟。

1

下载并安装 Cherry Studio

访问 cherry-ai.com 或 GitHub Releases 下载对应平台的安装包，双击安装。
2

拿到 SSOW API key

登录 https://token.ssow.org，进入「API 密钥」页面，新建一个 key 并复制（形如 sk-xxxx...，只显示一次）。
3

在 Cherry Studio 添加 SSOW

左下角设置图标 → 「模型服务」 → 「添加」 → 类型选「OpenAI」，按下面表格填字段。
为什么选「OpenAI」类型而不是「自定义」？因为 SSOW 完全兼容 OpenAI 协议，选 OpenAI 类型后 Cherry Studio 可以直接调用「获取模型列表」自动拉取可用模型。

支持的模型

SSOW 转发 OpenAI 和 Anthropic 两大体系的模型，全部按 token 用量计费，没有月度订阅。

OpenAI GPT 系列

模型 ID适合场景上下文
gpt-4o日常对话首选，多模态128K
gpt-4-turbo稳定高性能版本128K
gpt-4深度推理8K / 32K
gpt-3.5-turbo便宜快，简单任务16K

Anthropic Claude 系列

模型 ID适合场景上下文
claude-3-5-sonnet-20241022代码、长文，性价比之王200K
claude-3-opus-20240229最强推理，复杂任务200K
claude-3-haiku-20240307速度快、便宜200K

三句话选模型

日常聊天 → GPT-4o；写代码、读长文档 → Claude 3.5 Sonnet；批量简单任务（翻译、摘要）→ GPT-3.5 Turbo 或 Claude 3 Haiku。

配置 SSOW

Cherry Studio 设置界面
模型服务设置页

表单填这些

字段值
服务商OpenAI（不要选「自定义 OpenAI」）
名称SSOW（任意，能区分就行）
API 地址https://token.ssow.org
API 密钥sk-xxx，从 SSOW 后台复制
其他字段全部留空 / 默认

API 地址别加 /v1

Cherry Studio 会自动在 base URL 后面拼 /v1/chat/completions。手动加 /v1 会变成 /v1/v1/... 然后 404。如果你的版本要求显式带 /v1，那就只填 https://token.ssow.org，不要再加。

添加模型

填完上面三个字段后，点底部的「管理模型」或「获取模型列表」，Cherry Studio 会请求 /v1/models，自动列出 SSOW 可用的所有模型，勾选启用即可。

如果自动获取失败（部分版本有 bug），手动添加这几个最常用的：

手动添加的模型 IDtext
gpt-4o
gpt-4-turbo
gpt-3.5-turbo
claude-3-5-sonnet-20241022
claude-3-opus-20240229
claude-3-haiku-20240307

搞定

回到主对话窗口，左上角模型下拉就能看到 SSOW 下的全部模型。选一个发条消息验证一下。

API 配置详解

必填三件套

字段SSOW 的值说明
API 地址https://token.ssow.org不要带 /v1 后缀
API 密钥sk-xxx从 SSOW 后台「API 密钥」获取
组织 ID（留空）OpenAI 官方的字段，SSOW 不需要
API 版本（留空）Azure OpenAI 才用，普通 OpenAI / SSOW 不填

网络配置

国内访问 SSOW 一般直连即可。如果公司 / 学校网络要求走代理，在「设置 → 网络」配置 HTTP/HTTPS 代理：

网络设置json
{
  "proxy": {
    "enabled": true,
    "type": "http",
    "host": "127.0.0.1",
    "port": 7890
  },
  "timeout": 60000,
  "max_retries": 3
}

超时设置

长文档分析、复杂代码生成时单次响应可能超 60 秒。如果经常超时，把 timeout 调到 120000（2 分钟）。

模型参数

每个对话都能单独调这几个参数。在对话窗口右侧栏可以临时改，全局默认值在「设置 → 模型」改。

参数范围什么时候改
Temperature0 ～ 2代码 / 翻译 → 0.2；闲聊 → 0.7；创意写作 → 1.0+
Top P0 ～ 1默认 1，一般不动
Max Tokens1 ～ 模型上限想控制成本就限制小一点；想要长输出就调大
Presence Penalty-2 ～ 2回答总爱重复同一话题时调正值
Frequency Penalty-2 ～ 2用词太单调时调正值

常用预设

场景化预设yaml
# 代码生成
temperature: 0.2
top_p: 1
max_tokens: 4096

# 严谨问答（资料整理、文档总结）
temperature: 0.3
top_p: 0.9

# 创意写作
temperature: 0.95
presence_penalty: 0.6
frequency_penalty: 0.3

# 翻译
temperature: 0.1
top_p: 0.8

多模型切换

会话内切换

对话窗口顶部的模型下拉，可以随时切换。同一个对话里前几轮用 GPT-4o，后面切到 Claude 接着聊也没问题，上下文照样保留。

并排对比

点击发送按钮旁边的「@」选多个模型，同一条消息同时发出去。常用对比：

  • GPT-4o vs Claude 3.5 Sonnet → 选答得更准的
  • Sonnet vs Opus → 看复杂任务值不值得多花钱用 Opus
  • GPT-3.5 vs Claude Haiku → 比较廉价模型的实际表现

并排对比的成本

同一条消息发 N 个模型 = N 倍 token 消耗。不要长期开着对比，挑关键问题时用一下就好。

提示词模板

Cherry Studio 把「提示词」叫「助手」。每个助手 = 系统提示词 + 模型参数 + 默认模型。

从模板库添加

左侧助手列表 → 「+ 助手」 → 浏览内置模板（翻译、写作、SQL 助手、代码审查等）。点一下就能添加到自己的列表。

自建一个代码审查助手

自定义助手yaml
名称：代码审查
默认模型：claude-3-5-sonnet-20241022
Temperature：0.3
Max Tokens：4096

系统提示词：
你是资深软件工程师，专门做代码审查。每次审查请覆盖：
1. 正确性 - 是否有 bug、边界处理、错误处理
2. 安全性 - SQL 注入、XSS、密钥泄露等隐患
3. 性能 - N+1 查询、不必要的同步阻塞、内存泄漏
4. 可读性 - 命名、注释、复杂度
5. 测试 - 哪些路径需要补测试

输出格式：每个问题用「严重/一般/建议」标记优先级，附修复代码。

项目专属助手

每个项目建一个助手，把项目的技术栈、命名规范、目录结构写进系统提示词。这样不用每次对话都重复说明背景。

上下文管理

每次发消息，Cherry Studio 都会把历史对话全部带上。对话越长 token 消耗越大，控制好上下文能省一大笔钱。

关键设置

设置默认建议
上下文消息数105 ～ 15，够用即可
上下文 token 上限无限制设个 8K 或 16K，避免一不小心烧到 50 美金
保留系统消息是保留
附件历史是如果对话不需要回看历史图片，关掉省 token

什么时候新建对话

  • 话题完全切换 → 新建（让模型从头思考，不被旧内容干扰）
  • 对话超过 30 轮 → 新建（token 成本累积太高）
  • 模型开始「忘事」、答非所问 → 新建（可能撞上下文上限了）

最佳实践

选对模型

你想做什么用哪个模型
日常问答 / 写邮件GPT-4o
写代码 / 读代码Claude 3.5 Sonnet
读 100 页 PDF / 长文档分析Claude 3.5 Sonnet（200K 上下文）
数学、复杂逻辑推理Claude 3 Opus 或 GPT-4
简单翻译、批量摘要Claude 3 Haiku 或 GPT-3.5 Turbo
看图说话 / OCRGPT-4o

API key 安全

保护好你的 sk-xxx

  • 不要在公共电脑上登录 Cherry Studio 然后忘了登出
  • 怀疑 token 泄露，立刻去 SSOW 后台撤销并重建
  • 团队共用 SSOW 账号时，每人单独建一个 key 并标好备注
  • Cherry Studio 把 key 加密存在本地，不会上传，但同步配置功能除外（默认关闭）

降低成本

  • 简单任务用便宜模型，能省 10 倍以上
  • 限制 max_tokens，避免模型啰嗦输出 4K 字
  • 开流式输出，提前看到结果可以及时打断
  • 定期清理无用对话，减少误触历史长对话

相关资源

SSOW 控制台

管理 API 密钥、查看用量、充值

下载 Cherry Studio

获取最新版本

Cherry Studio 官方文档

完整用户手册

社区讨论

GitHub Discussions

文档/Claude Code

Claude Code 接入 SSOW 中转服务

学习如何在 Claude Code 命令行工具中配置 SSOW 中转服务，高效进行 AI 辅助编程。

实时同步GET /v1/models点击模型名称即可复制

SSOW 支持的模型清单

共 21 个 模型，覆盖 OpenAI GPT 与 Google Gemini / Nano Banana 系列。统一通过 /v1 兼容接口调用。

OpenAI · GPT 系列

共 11 个模型

适用于 Codex、Cursor、Cline、Cherry Studio 等 OpenAI 协议客户端

对话与推理

通用对话、推理、长上下文

编程专用

Codex 系列，代码生成与重构

图像生成

文生图、图像编辑

Google · Gemini / Nano Banana 系列

共 10 个模型

适用于 Gemini、图像生成与 Google 兼容模型调用场景

Gemini 对话与推理

Google Gemini 系列，通用对话与多模态推理

Nano Banana 图像生成

图像生成、图片编辑与视觉创作

模型列表已按当前支持的 OpenAI GPT 和 Google Gemini / Nano Banana 更新。点击模型名称即可复制 model id。

安装指南

快速安装 Claude Code

配置 SSOW

接入 SSOW 中转服务

基本使用

常用命令和技巧

Claude Code 接入 SSOW

Claude Code 是 Anthropic 官方推出的命令行 AI 编程助手，原生支持通过 ANTHROPIC_BASE_URL 切换 API 端点。把它指向 SSOW（https://token.ssow.org），就能用一个 token 直接调用 Claude Sonnet / Opus，按 token 实际用量计费。

适合谁

  • 没有 Claude Pro 订阅，但想用 Claude Code CLI 写代码
  • 团队多人共享额度，需要按 token 精确计费的开发者
  • 国内访问 Anthropic 官方端点不稳定，需要中转的用户

和官方的区别

对比项Anthropic 官方SSOW
计费方式Claude Pro 月付 $20 起按 token 用量付费
额度限制每 5 小时消息数软限制只看 token 总量
接入方式申请 console API key一个 sk- token 全搞定
国内访问需要稳定网络国内直连

原生兼容

基于 ANTHROPIC_BASE_URL 标准接入，与 Claude Code 完全兼容

按量计费

只为实际使用的 token 付费，无固定订阅成本

支持全模型

Claude Sonnet / Opus / Haiku 系列均可调用

国内直连

国内主流网络可直连，无需额外代理

安装 Claude Code

Claude Code 通过 npm 全局安装，要求 Node.js 18 及以上版本。

Terminalbash
# 全局安装
npm install -g @anthropic-ai/claude-code

# 验证安装
claude --version

Node.js 版本

建议使用 Node.js 18 LTS 或 20 LTS。如果未安装 Node.js，推荐使用 nvm / fnm 等版本管理工具。

三步接入 SSOW

通常不超过 60 秒。

1

登录 SSOW 后台

访问 https://token.ssow.org，注册或登录账号。
2

创建 API 密钥

进入「API 密钥」页面，点击「新建」。token 形如 sk-xxxx...，只显示一次，立刻复制保存。
3

设置环境变量

把 base_url 和 api_key 填到 Claude Code 识别的环境变量里：
Terminalbash
export ANTHROPIC_BASE_URL=https://token.ssow.org
export ANTHROPIC_API_KEY=sk-xxxx...

claude

跑 claude，就走 SSOW。

持久化到 Shell 配置

上面的 export 只对当前会话生效。要每次开新终端都自动加载，写到 ~/.zshrc 或 ~/.bashrc：

Terminalbash
# 追加到 ~/.zshrc（zsh 用户）或 ~/.bashrc（bash 用户）
echo 'export ANTHROPIC_BASE_URL=https://token.ssow.org' >> ~/.zshrc
echo 'export ANTHROPIC_API_KEY=sk-xxxx...' >> ~/.zshrc

# 立即生效
source ~/.zshrc

Windows 用户

PowerShellpowershell
# PowerShell（当前会话）
$env:ANTHROPIC_BASE_URL = "https://token.ssow.org"
$env:ANTHROPIC_API_KEY = "sk-xxxx..."

# 永久生效（用户级环境变量）
[Environment]::SetEnvironmentVariable("ANTHROPIC_BASE_URL", "https://token.ssow.org", "User")
[Environment]::SetEnvironmentVariable("ANTHROPIC_API_KEY", "sk-xxxx...", "User")

安全提示

token 等同密码，不要写进代码、不要提交到 Git、不要发到聊天群。怀疑泄露立即去后台撤销重建。

验证配置

检查环境变量是否生效：

Terminalbash
echo $ANTHROPIC_BASE_URL
# 应输出: https://token.ssow.org

echo $ANTHROPIC_API_KEY
# 应输出: sk-xxxx...（前几位）

启动 Claude Code，发一条简单问题测试：

Terminalbash
claude
> 你好，请用一句话介绍自己

看到 Claude 回复

收到 Claude 的回复就说明 SSOW 接入成功。后台「用量统计」会同步出现这次调用的 token 消耗。

基本使用

启动交互会话

Terminalbash
# 在项目根目录启动
cd ~/your-project
claude

# Claude 会读取当前目录上下文，可以直接说：
# > 帮我看看 src/auth.ts 里 validateToken 函数有没有问题
# > 把这个函数重构成异步的
# > 给这个模块写单元测试

指定模型

通过 ANTHROPIC_MODEL 环境变量指定默认模型：

Terminalbash
# 使用 Claude 3.5 Sonnet（推荐，编码能力强）
export ANTHROPIC_MODEL=claude-3-5-sonnet-20241022

# 使用 Claude 3 Opus（最强推理）
export ANTHROPIC_MODEL=claude-3-opus-20240229

# 使用 Claude 3 Haiku（快、省）
export ANTHROPIC_MODEL=claude-3-haiku-20240307

会话内常用命令

命令说明
/help查看可用命令
/clear清空当前对话上下文
/model查看或切换当前模型
/cost查看本次会话的 token 消耗
/exit退出会话

最佳实践

按场景选模型

场景推荐模型理由
日常代码生成Claude 3.5 Sonnet代码质量高，速度合适
架构设计、复杂重构Claude 3 Opus推理深度最好
简单问答、commit messageClaude 3 Haiku便宜 10x，速度快
大型代码库分析Claude 3.5 Sonnet200K 上下文 + 高性价比

控制 token 消耗

  • 不需要 Claude 看整个项目时，用 /clear 清空上下文
  • 简单任务（写注释、commit message）切到 Haiku
  • 会话结束前用 /cost 看消耗，及时调整
  • 在 .gitignore 加上 .claude/，避免缓存提交进仓库

项目级配置

在项目根目录建 CLAUDE.md，写下项目约定，Claude Code 会自动加载：

CLAUDE.mdmarkdown
# CLAUDE.md

## 技术栈
- TypeScript + Next.js 16
- Tailwind CSS + shadcn/ui
- 数据库：Supabase (PostgreSQL)

## 代码风格
- 使用函数组件，不用 class
- 优先用 server components，客户端逻辑加 "use client"
- 命名：组件 PascalCase，hooks use- 前缀

## 测试
- 用 Vitest，测试文件放在 __tests__ 目录

常见问题

报错 401 / Authentication failed

API 密钥无效或没生效。检查：

Terminalbash
# 1. 确认环境变量被读取
echo $ANTHROPIC_API_KEY

# 2. 确认 token 没有多余空格
# 复制时注意首尾不要带空白字符

# 3. 直接 curl 测一下
curl https://token.ssow.org/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-3-5-sonnet-20241022","max_tokens":50,"messages":[{"role":"user","content":"hi"}]}'

报错 connection timeout

网络不通。先 ping 一下，再检查公司 / 学校代理是否拦截：

Terminalbash
# 测试连通性
curl -I https://token.ssow.org

# 走 HTTP 代理
export HTTPS_PROXY=http://127.0.0.1:7890
claude

余额不足 / 用量超限

登录 SSOW 后台 https://token.ssow.org，在「账户余额」页面充值，或在「用量统计」查看具体消耗。

切换回官方 API

Terminalbash
# 临时切回官方
unset ANTHROPIC_BASE_URL
export ANTHROPIC_API_KEY=sk-ant-xxxx  # 官方 key

# 永久切回：删掉 .zshrc 里的两行 export 即可

相关资源

SSOW 控制台

管理 API 密钥、查看用量、充值

Claude Code 官方文档

Anthropic 官方使用指南

Claude 模型 API 文档

模型名称、参数、上下文限制

文档/Droid / Pi

在 Droid 和 Pi 中使用 SSOW

通过 OpenAI 兼容方式将 SSOW 接入 Droid 与 Pi 两款 CLI 编码 Agent，使用 GPT 和 Claude 系列模型。

实时同步GET /v1/models点击模型名称即可复制

SSOW 支持的模型清单

共 21 个 模型，覆盖 OpenAI GPT 与 Google Gemini / Nano Banana 系列。统一通过 /v1 兼容接口调用。

OpenAI · GPT 系列

共 11 个模型

适用于 Codex、Cursor、Cline、Cherry Studio 等 OpenAI 协议客户端

对话与推理

通用对话、推理、长上下文

编程专用

Codex 系列，代码生成与重构

图像生成

文生图、图像编辑

Google · Gemini / Nano Banana 系列

共 10 个模型

适用于 Gemini、图像生成与 Google 兼容模型调用场景

Gemini 对话与推理

Google Gemini 系列，通用对话与多模态推理

Nano Banana 图像生成

图像生成、图片编辑与视觉创作

模型列表已按当前支持的 OpenAI GPT 和 Google Gemini / Nano Banana 更新。点击模型名称即可复制 model id。

Droid 配置

Factory CLI BYOK 接入

Pi 配置

pi.dev 自定义模型

模型选择建议

按场景选择合适的模型

在 Droid 和 Pi 中使用 SSOW

Droid 和 Pi 都按 OpenAI-compatible 方式接入 SSOW。配置完成后，即可在两个 CLI Agent 中使用 GPT 和 Claude 系列模型。

配置项值
Base URLhttps://token.ssow.org/v1
API Key仪表盘 → API 密钥 中创建的 sk-xxx
推荐模型gpt-4o, claude-3.5-sonnet
轻量任务gpt-4o-mini, claude-3-haiku

OpenAI 兼容协议

两个工具均通过 OpenAI 兼容的 Chat Completions 协议调用 SSOW，因此 API 地址需要带上 /v1 后缀。

Droid

Droid 是 Factory 的命令行编码 Agent，通过 BYOK（Bring Your Own Key）方式接入第三方模型。

第一步：设置环境变量

先把 SSOW 的 API 密钥放进环境变量：

Terminalbash
export SSOW_API_KEY=sk-xxxxxxxxxxxxxxxx

第二步：编辑 Droid 配置文件

编辑 ~/.factory/settings.json，添加 SSOW 自定义模型：

~/.factory/settings.jsonjson
{
  "customModels": [
    {
      "model": "gpt-4o",
      "displayName": "SSOW GPT-4o",
      "baseUrl": "https://token.ssow.org/v1",
      "apiKey": "${SSOW_API_KEY}",
      "provider": "openai",
      "maxOutputTokens": 16384
    },
    {
      "model": "gpt-4o-mini",
      "displayName": "SSOW GPT-4o Mini",
      "baseUrl": "https://token.ssow.org/v1",
      "apiKey": "${SSOW_API_KEY}",
      "provider": "openai",
      "maxOutputTokens": 16384
    },
    {
      "model": "claude-3.5-sonnet",
      "displayName": "SSOW Claude 3.5 Sonnet",
      "baseUrl": "https://token.ssow.org/v1",
      "apiKey": "${SSOW_API_KEY}",
      "provider": "openai",
      "maxOutputTokens": 16384
    }
  ]
}

第三步：交互模式使用

运行 droid 进入交互模式，使用 /model 命令选择 SSOW GPT-4o：

Terminalbash
droid
> /model SSOW GPT-4o

Headless 模式

通过 --model 参数指定 SSOW 模型，按数字索引匹配 customModels 中的顺序：

Terminalbash
# 使用第一个模型 GPT-4o
droid exec --model "custom:SSOW-GPT-4o-0" "summarize this repository"

# 使用第二个模型 GPT-4o Mini
droid exec --model "custom:SSOW-GPT-4o-Mini-1" "fix typos in docs"

# 使用第三个模型 Claude 3.5 Sonnet
droid exec --model "custom:SSOW-Claude-3.5-Sonnet-2" "review the recent changes"

模型命名规则

Headless 模式中模型名格式为 custom:<displayName 去空格>-<索引>，索引从 0 开始，对应 customModels 数组顺序。

Pi

Pi 是 pi.dev 的命令行编码 Agent。自定义模型配置文件是 ~/.pi/agent/models.json。

第一步：设置环境变量

同样先把 SSOW 的 API 密钥放进环境变量：

Terminalbash
export SSOW_API_KEY=sk-xxxxxxxxxxxxxxxx

第二步：编辑 Pi 模型配置

编辑 ~/.pi/agent/models.json，添加 SSOW provider：

~/.pi/agent/models.jsonjson
{
  "providers": {
    "tokengo": {
      "baseUrl": "https://token.ssow.org/v1",
      "api": "openai-responses",
      "apiKey": "SSOW_API_KEY",
      "authHeader": true,
      "models": [
        {
          "id": "gpt-4o",
          "name": "SSOW GPT-4o",
          "reasoning": true,
          "maxTokens": 16384
        },
        {
          "id": "gpt-4o-mini",
          "name": "SSOW GPT-4o Mini",
          "reasoning": true,
          "maxTokens": 16384
        },
        {
          "id": "claude-3.5-sonnet",
          "name": "SSOW Claude 3.5 Sonnet",
          "reasoning": true,
          "maxTokens": 16384
        }
      ]
    }
  }
}

apiKey 字段说明

注意 apiKey 字段填写的是环境变量名（SSOW_API_KEY），不是密钥本身。Pi 会自动从环境变量读取实际值。

第三步：启动 Pi

通过 --provider 和 --model 参数指定 SSOW 模型：

Terminalbash
# 使用 GPT-4o
pi --provider tokengo --model gpt-4o

# 使用 Claude 3.5 Sonnet
pi --provider tokengo --model claude-3.5-sonnet

在 Pi 交互界面里也可以用 /model 命令切换到 SSOW GPT-4o 等模型。

模型选择建议

Droid 和 Pi 都是面向编码场景的 Agent，模型选择直接影响代码质量和响应速度。

场景推荐模型说明
大型重构、复杂调试claude-3.5-sonnet代码理解最深，输出最稳定
日常编码、解释代码gpt-4o响应快，综合能力强
简单修改、文档生成gpt-4o-mini成本低，足够日常使用
快速问答、单文件改动claude-3-haiku极快响应，按量计费便宜

按需切换

建议在 settings.json / models.json 里同时配置多个模型，遇到复杂任务时用 /model 切换到 Claude 3.5 Sonnet，简单任务用 mini 系列省钱。

验证配置

配置完成后，在 Droid 或 Pi 中发一条 ping。再到 SSOW 仪表盘 → 使用记录 中查看调用记录，能看到对应模型就配置成功。

使用 curl 直接测试

也可以绕过 Agent，直接用 curl 验证 SSOW 端点是否通：

Terminalbash
curl https://token.ssow.org/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SSOW_API_KEY" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "ping"}]
  }'

返回 200 且包含 choices 字段即为成功。如果返回 401，检查环境变量是否正确导出；返回 404，检查 baseUrl 是否带 /v1。

常见问题

Droid 找不到自定义模型

检查 ~/.factory/settings.json 是否为合法 JSON（末尾不能有多余逗号），并重启 droid 进程。环境变量需要在启动 droid 的同一个 shell 中导出。

Pi 报 401 未授权

确认 ~/.pi/agent/models.json 中 apiKey 填的是环境变量名而不是密钥值；同时检查 echo $SSOW_API_KEY 能正确输出密钥。

请求超时或无响应

网络问题居多。先用上面的 curl 命令测试 SSOW 端点，再检查本地是否有代理工具拦截了流量。如果 curl 通但 Agent 不通，提高 maxOutputTokens 限制并重试。

切换模型后行为异常

Claude 和 GPT 系列对 system prompt 的处理略有差异，切换模型后建议新建会话，避免历史上下文造成的格式混乱。

相关资源

Factory Droid 官方文档

Droid CLI 安装、命令、BYOK 配置说明

Pi 官方文档

Pi CLI 安装与自定义模型配置

SSOW 仪表盘

管理 API 密钥、查看调用记录与余额

文档/Hermes

Hermes Agent（爱马仕）接入 SSOW

把 Hermes Agent 的自定义 endpoint 指到 SSOW，通过 OpenAI Chat Completions 协议使用 GPT 和 Claude 系列模型。

实时同步GET /v1/models点击模型名称即可复制

SSOW 支持的模型清单

共 21 个 模型，覆盖 OpenAI GPT 与 Google Gemini / Nano Banana 系列。统一通过 /v1 兼容接口调用。

OpenAI · GPT 系列

共 11 个模型

适用于 Codex、Cursor、Cline、Cherry Studio 等 OpenAI 协议客户端

对话与推理

通用对话、推理、长上下文

编程专用

Codex 系列，代码生成与重构

图像生成

文生图、图像编辑

Google · Gemini / Nano Banana 系列

共 10 个模型

适用于 Gemini、图像生成与 Google 兼容模型调用场景

Gemini 对话与推理

Google Gemini 系列，通用对话与多模态推理

Nano Banana 图像生成

图像生成、图片编辑与视觉创作

模型列表已按当前支持的 OpenAI GPT 和 Google Gemini / Nano Banana 更新。点击模型名称即可复制 model id。

准备

获取 SSOW Token

配置

hermes model 向导接入

可用模型

GPT 与 Claude 全系列

Hermes Agent（爱马仕）

Hermes Agent 走 OpenAI-compatible chat/completions 协议。把它的自定义 endpoint 指到 SSOW， 就能在 Hermes 里使用 gpt-4o、gpt-4o-mini、claude-3.5-sonnet 等模型。

OpenAI 兼容协议

Hermes 默认通过 /v1/chat/completions 调用模型，因此 Base URL 需要带上 /v1 后缀， 客户端会自动拼接路径。

准备

配置项值
SSOW Token在仪表盘 → API 密钥 中创建，格式是 sk-xxxxxxxxxxxxxxxx
Base URLhttps://token.ssow.org/v1
推荐模型gpt-4o 日常使用更稳，gpt-4o-mini 适合轻量任务和成本敏感场景

获取 API 密钥

登录 SSOW 主站 → 进入仪表盘 → 找到 「API 密钥」入口 → 创建一个新的密钥并复制保存。 密钥只会展示一次，请妥善保存。

配置

直接运行 Hermes 自带的模型配置向导：

Terminalbash
hermes model

选择自定义 endpoint

按提示依次选择：

向导选项text
More providers...
Custom endpoint (enter URL manually)

填入 SSOW 信息

然后填入：

配置内容text
API base URL: https://token.ssow.org/v1
API key: sk-xxxxxxxxxxxxxxxx

选择模型

接着在模型列表里选择：

模型名称text
gpt-4o

启动会话

配置完成后运行：

Terminalbash
hermes chat

无需手动改配置

Hermes 的 hermes model 向导会自动把上述信息写入 ~/.hermes/config.json， 下次启动会话时直接生效，不需要再手动编辑。

可用模型

SSOW 支持 OpenAI GPT 和 Anthropic Claude 两大系列模型。在 Hermes 中可以根据任务复杂度灵活切换。

模型适用场景
gpt-4o推荐默认选择，复杂编码、多文件重构、通用任务
gpt-4o-mini普通问答、简单改文案、小段代码，速度快、成本低
gpt-4-turbo长上下文场景，128K 窗口，适合阅读大段代码
claude-3.5-sonnet代码生成质量高，工具调用稳，适合 Agent 任务
claude-3-opus复杂推理和长任务规划，质量优先
claude-3-haiku极简任务，响应最快、单价最低

切换模型

想临时换一个模型，再次运行 hermes model 选择即可，配置会覆盖原有的模型字段，但 Base URL 和 API key 会保留。

测试

进入 Hermes 后，直接发一句话：

测试消息text
你好，用一句话介绍你自己

能正常回复就表示配置成功。如果想确认实际走的是 SSOW 而不是缓存，可以问一句更具体的：

进阶测试text
帮我用 Python 写一个快速排序，要求带注释

看到流式输出代码块即代表 Chat Completions 接口已经打通，SSOW 也会在仪表盘记录这次调用。

常见问题

Empty response from model

Hermes 使用的是 /v1/chat/completions。在 hermes model 里填写 Base URL：https://token.ssow.org/v1，让 Hermes 自动拼出 /chat/completions。

重新运行 hermes model，确认 Base URL、API key、Model name 三项。

看到 response.created / response.completed

这表示客户端收到了 Responses API 的 SSE 事件流。Hermes 需要 Chat Completions 格式，SSOW 的/v1/chat/completions 会自动转换。遇到这种情况，优先检查：

  • base_url 是否是 https://token.ssow.org/v1
  • 请求路径是否是 /v1/chat/completions
  • Hermes 是否升级到了支持自定义 endpoint 的最新版本

模型不支持

老模型名如 gpt-3.5、gpt-4-32k 已不在推荐列表中。 重新运行 hermes model，选择 gpt-4o 或claude-3.5-sonnet。

401 Unauthorized

检查 API key 是否复制完整，以及是否在 SSOW 仪表盘中处于「启用」状态。如果 key 已被禁用或过期， 重新生成一个再粘贴回 hermes model 向导即可。

余额不足 / 429 限流

SSOW 按量计费，到 仪表盘 → 用量 查看剩余余额，必要时充值。429 通常是当前 key 的并发太高， 可以稍后重试或在仪表盘中再创建一把 key 用于不同的工作流。

参考

Hermes Agent AI Providers

官方支持的供应商列表与协议说明

Hermes Agent Configuration

完整的配置参数与本地配置文件结构

SSOW 仪表盘

管理 API 密钥、查看用量与计费

文档/GPT-Image-2

GPT-Image-2 绘图教程

通过 SSOW 调用 OpenAI gpt-image-2 模型，进行高保真文生图、图片编辑与 Cherry Studio 绘画接入。

实时同步GET /v1/models点击模型名称即可复制

SSOW 支持的模型清单

共 21 个 模型，覆盖 OpenAI GPT 与 Google Gemini / Nano Banana 系列。统一通过 /v1 兼容接口调用。

OpenAI · GPT 系列

共 11 个模型

适用于 Codex、Cursor、Cline、Cherry Studio 等 OpenAI 协议客户端

对话与推理

通用对话、推理、长上下文

编程专用

Codex 系列，代码生成与重构

图像生成

文生图、图像编辑

Google · Gemini / Nano Banana 系列

共 10 个模型

适用于 Gemini、图像生成与 Google 兼容模型调用场景

Gemini 对话与推理

Google Gemini 系列，通用对话与多模态推理

Nano Banana 图像生成

图像生成、图片编辑与视觉创作

模型列表已按当前支持的 OpenAI GPT 和 Google Gemini / Nano Banana 更新。点击模型名称即可复制 model id。

前置准备

获取 GPT 分组 API Key

调用方式

Images API 文生图与图生图

Cherry Studio 接入

图形界面绘画应用配置

GPT-Image-2 简介

gpt-image-2 是 OpenAI 最新一代多模态图像模型，支持高保真文生图、参考图编辑、局部修改、4K 输出和长文本可读印刷。在 SSOW 中，gpt-image-2 与其他 GPT 模型共享同一个调用域名 https://token.ssow.org，无需切换分组或单独申请密钥，使用 GPT 类令牌即可直接调用。

高保真出图

支持 4K（3840×2160）输出，保留细节与文字。

文生图 + 图生图

一个模型同时承担生成与编辑两类工作流。

OpenAI 协议兼容

走标准 Images API，主流客户端零改造接入。

本文目标

帮助你在 5 分钟内通过 SSOW 调用 gpt-image-2：包含 curl 示例、参数表、Cherry Studio 接入流程，以及不同 API 入口的支持情况说明。

前置准备

在 SSOW 中调用 gpt-image-2 前，请确认以下两件事：

1

获取 GPT 类 API Key

登录 SSOW 控制台，在「令牌管理」页面创建一个 GPT 分组的 Token，复制以 sk- 开头的密钥。
2

确认账户余额

gpt-image-2 按图计费，quality=high 与 4K 分辨率消耗较高，请确保账户有充足余额。

无需 sora 分组

与部分中转平台不同，SSOW 的 gpt-image-2 与 GPT-4o、GPT-5 等文本模型共用同一个 GPT 分组令牌，不需要单独创建 sora 分组。

调用方式

OpenAI 把图片相关能力分成 Responses API、Images API、Chat Completions API 三类。对 SSOW 的 gpt-image-2 来说，出图请优先使用 Images API。

APIOpenAI 官方用途SSOW gpt-image-2 使用建议建议
Responses API分析图片、调用工具生成图片不支持作为 gpt-image-2 的出图入口。不支持
Images API生成与编辑图片支持文生图与图片编辑，是推荐的调用方式。推荐
Chat Completions API分析图片输入、生成文本或音频size、quality、output_format 等图像参数不会按图片接口生效。不支持

方式一：Images API（推荐）

Images API 分为文生图和图片编辑两个接口：

  • 文生图：POST https://token.ssow.org/v1/images/generations
  • 图片编辑 / 图生图：POST https://token.ssow.org/v1/images/edits

推荐用法

仅根据提示词生成新图，使用 /v1/images/generations；需要上传参考图编辑或图生图，使用 /v1/images/edits。

文生图：/v1/images/generations

curl --location 'https://token.ssow.org/v1/images/generations' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_SSOW_API_KEY' \
  --data '{
    "model": "gpt-image-2",
    "prompt": "一只橘猫戴着橙色围巾抱着水獭，温暖插画风格",
    "size": "3840x2160",
    "quality": "high",
    "output_format": "png",
    "response_format": "url",
    "n": 1
  }'

文生图参数说明：

参数类型支持情况说明
modelstring支持固定填写 gpt-image-2。
promptstring支持图片描述提示词，建议写清楚主体、场景、风格、比例和文字内容。
ninteger仅支持 1只支持一次返回 1 张图。n: 2、n: 4 这类多图数量不支持。
sizestring支持支持 auto 与 1024x1024、1536x1024、1024x1536、3840x2160 等。
qualitystring支持可选 low、medium、high、auto。
response_formatstring支持可选 url、b64_json。默认建议用 url。
output_formatstring部分支持推荐 png 或 jpeg，webp 不建议使用。
output_compressioninteger支持仅在 output_format=jpeg 时使用，取值 0–100。
backgroundstring部分支持建议使用默认值或 opaque，transparent 不支持。
moderationstring支持可选 auto、low，安全审核参数。
streamboolean不支持请勿开启。
partial_imagesinteger不支持依赖 stream 的中间图能力，不支持。

图片编辑 / 图生图：/v1/images/edits

/v1/images/edits 使用 multipart/form-data 上传图片。image 是二进制图片文件，prompt 写清楚希望怎么修改图片。

curl --location 'https://token.ssow.org/v1/images/edits' \
  --header 'Authorization: Bearer YOUR_SSOW_API_KEY' \
  --form 'model="gpt-image-2"' \
  --form 'prompt="保留主体，在右上角加一枚红色小印章，印章上写 DEMO"' \
  --form 'image=@"/path/to/your-image.jpg"' \
  --form 'size="1024x1024"' \
  --form 'quality="high"' \
  --form 'output_format="png"' \
  --form 'response_format="url"'

图片编辑参数说明（仅列出与文生图差异）：

参数类型支持情况说明
imagefile支持必填，上传要编辑的图片二进制文件，建议一次只上传 1 张。
maskfile支持可选，局部修改时可传 PNG mask；不传则按整图编辑理解。
input_fidelitystring支持编辑时可传 high，用于尽量保留原图主体和细节。

局部修改

mask 建议使用 PNG 图片，透明区域表示允许模型重点修改的位置；不传 mask 时，模型会根据提示词对整张图进行编辑。

通用说明

尺寸与质量

常用尺寸：

  • 1024 × 1024：正方形
  • 1536 × 1024：横向
  • 1024 × 1536：纵向
  • 2048 × 2048：2K 正方形
  • 3840 × 2160：4K 横向
  • 2160 × 3840：4K 纵向
  • auto：自动（默认）

尺寸限制：

  • 最大边长必须 ≤ 3840 像素
  • 宽和高都必须是 16 的倍数
  • 长边与短边比例不超过 3:1
  • 总像素数 ≥ 655,360 且 ≤ 8,294,400

质量选项： low（草稿） / medium / high（推荐） / auto（默认）

参数怎么选

  • 最简单文生图：只传 model、prompt，并把 n 设为 1。
  • 想要更高清晰度：加 quality: "high"。
  • 想控制尺寸：加 size，比如 1024x1024 或 1536x1024。
  • 想拿图片链接：使用默认 response_format: "url"。
  • 程序自行保存图片：使用 response_format: "b64_json"。
  • 不要把 n 设置成大于 1，多张图请自己循环请求。

返回结果

默认返回图片下载地址：

{
  "created": 1776923999,
  "data": [
    {
      "url": "https://external-resources.ssgoo.net/file_download/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "revised_prompt": "..."
    }
  ]
}

返回的 url 即为生成的图片地址，直接访问即可下载。revised_prompt 是模型实际使用前改写过的提示词，看到它是正常现象，不是报错。

如果请求里传了 "response_format": "b64_json"，返回内容会变成 Base64 图片数据：

{
  "created": 1776923999,
  "data": [
    {
      "b64_json": "iVBORw0KGgoAAAANSUhEUgAA...",
      "revised_prompt": "..."
    }
  ]
}

这时响应里通常没有 url，需要客户端自己把 b64_json 解码成图片文件。普通用户更推荐使用默认的 url，最容易保存和分享。

方式二：Responses API（不支持）

不支持

SSOW 的 gpt-image-2 不支持通过 /v1/responses 出图。请不要使用 image_generation 工具、input 或 input_image 来调用 gpt-image-2 生成图片。

需要文生图请使用 /v1/images/generations；需要上传图片编辑请使用 /v1/images/edits。

方式三：Chat Completions API（不支持）

不支持

SSOW 的 gpt-image-2 不支持通过 /v1/chat/completions 出图。请不要把 messages、image_url、size、quality、output_format 等参数放到 Chat Completions 里调用图片生成。

如果使用 Cherry Studio，请切换到「绘画」应用，并确保端点类型是 图像生成（OpenAI）。

给开发者

如果你的客户端只支持 Chat Completions，并且必须接入图片能力，建议优先改为支持 OpenAI Images API。不要把 /v1/chat/completions 当成 /v1/images/generations 的替代品。

在 Cherry Studio 中使用

Cherry Studio 自带「绘画」应用，可以直接通过图形界面调用 gpt-image-2，无需写代码。

1

准备 API Key

登录 SSOW 控制台，复制 GPT 分组的 API Key 到剪贴板。
2

安装 Cherry Studio

访问 Cherry Studio 官网下载并安装客户端。
3

新增提供商

打开 Cherry Studio，点击左下角设置按钮，进入「模型服务」页面，点击底部「添加」按钮新增提供商。提供商名称填 tokengo-gpt-image-2，「提供商类型」选择 New API，点击「确定」。
4

填写密钥与地址

在左侧列表中找到刚添加的提供商，将复制的 GPT 分组 API Key 填入「API 密钥」，「API 地址」填写：
https://token.ssow.org
注意：地址不要带 /v1，Cherry Studio 会自动拼接。
5

添加 gpt-image-2 模型

点击模型区域右侧「获取模型列表」，刷新后添加 gpt-image-2。如果列表中找不到，也可以点击「添加」手动输入模型 ID gpt-image-2。
6

设置端点类型

点击 gpt-image-2 右侧编辑按钮，进入编辑模型窗口，将「端点类型」设置为 图像生成（OpenAI），点击「保存」。
7

开始绘画

回到首页，点击顶部 + 按钮，在应用列表中选择「绘画」。左侧「提供商」选择 tokengo-gpt-image-2，「模型」选择 gpt-image-2。首次使用建议把图片尺寸、质量、敏感度都保持「自动」，生成数量保持 1。

绘图模式与编辑模式

绘图模式

只根据提示词生成新图。顶部选择「绘图」，输入提示词后点击发送即可。

编辑模式

上传参考图进行图生图或局部修改。顶部切换到「编辑」，左侧上传参考图，再输入修改要求。

使用建议

  • API 地址直接填 https://token.ssow.org，Cherry Studio 会自动拼接，无需手动补 /v1。
  • 模型列表里没有 gpt-image-2，请先在「管理」中刷新模型；仍然不能正常绘图，请检查端点类型是否为「图像生成（OpenAI）」。
  • 如果你在普通对话页中直接调用 gpt-image-2，建议关闭「流式输出」，避免返回内容解析异常；使用「绘画」应用时通常不需要额外处理。

常见问题

Cherry Studio 弹出 Failed to fetch

通常是请求连接被中断，可能与本机代理或网络环境有关。先检查代理设置，确认 Cherry Studio 能正常访问 https://token.ssow.org 后再重试：

curl -I https://token.ssow.org/v1/models

返回 Unexpected token '<'

说明客户端拿到的是 HTML 而不是 JSON，常见原因：

  • API 地址写错（多写或少写 /v1），请按 Cherry Studio 要求只填 https://token.ssow.org。
  • 本地代理把请求重定向到了 HTML 页面，关闭代理或改用直连后重试。
  • 网络环境拦截了请求，换网络或开关 Wi-Fi 重试。

提示「model not found」或「model not allowed」

检查请求体里的 model 字段是否严格写为 gpt-image-2，不要写成 gpt-image、gpt-image2 或 gpt_image_2。也请确认使用的是 GPT 分组令牌，而不是 Claude 分组令牌。

多张图请求被限制

gpt-image-2 仅支持 n=1。如果你需要多张候选，请在客户端循环调用 /v1/images/generations，每次请求传相同提示词即可。

生成耗时较长

quality=high + 4K 分辨率单张耗时通常 30–90 秒。如果你只是验证流程，建议先用 quality=low + 1024x1024 跑通，再切到高质量。

相关资源

SSOW 控制台

管理 API Key、查看用量与余额

OpenAI Images API 文档

官方参数说明与最新能力更新

Cherry Studio 下载

官方桌面客户端，内置绘画应用

文档/Chat Box

网站 Chat Box / Chat Bot 接入 SSOW

给官网、文档站或产品后台增加聊天窗口，可用作在线客服、站内 FAQ 助手，或接入 SSOW 的 AI Chat Bot。

推荐方案POST /v1/chat/completionsAPI Key 仅放后端

Chat Box 的推荐接入架构

对大多数网站来说，最稳的做法是：前端只负责聊天窗口 UI，消息先发到你自己的 /api/chat，再由后端去调用 https://token.ssow.org/v1。

纯客服浮窗

只展示微信、邮箱、表单或人工客服入口，最快上线。

FAQ 助手

适合文档站、帮助中心，用固定知识或轻量模型回答常见问题。

AI Chat Bot

适合产品介绍、售前咨询、站内助手，需要后端代理和模型调用。

如果你只是想先把聊天入口放到网站右下角，可以先完成前端浮窗；如果你希望它真的能智能回答，再继续接入 SSOW 的聊天接口。

前置准备

先准备 API Key、后端接口和知识内容

嵌入脚本版

先把右下角聊天浮窗放到页面里

AI Chat Bot

把前端消息接到 SSOW 的模型接口

Chat Box 简介

网站里的 Chat Box 通常有三种用途：在线客服、产品咨询和站内 AI 助手。对 SSOW 用户来说，最常见的是第三种，也就是把右下角聊天窗口接到 /v1/chat/completions，让模型根据你的业务提示词来回答。

官网客服

回答价格、功能、注册流程等售前问题。

文档助手

结合你的帮助文档，解释配置步骤和常见报错。

产品引导

在用户使用后台时，回答当前页面相关操作问题。

推荐边界

如果 Chat Bot 会涉及账户、订单、支付等敏感操作，建议只让它回答问题，不要直接执行高风险写操作；真正的提交、退款、修改数据仍应走你自己的业务接口和权限校验。

前置准备

开始前建议先准备下面三项：

1

获取 GPT 分组 API Key

登录 SSOW 控制台，创建 GPT 分组令牌。网站 Chat Box 通常建议先用 GPT 系列模型，后端调用时用 Bearer sk-xxxx... 认证。
2

准备一个后端接口

前端页面不要直接请求 SSOW，也不要把 API Key 写在浏览器脚本里。推荐在你自己的网站后端增加一个 /api/chat，由它转发到 SSOW。
3

整理好你的业务知识

至少先准备一版产品介绍、价格说明、FAQ、联系方式和升级路径。即便你还没做检索增强，这些内容也能先写进 system prompt 或后端配置里。

模型选择建议

如果你的 Chat Box 主要回答 FAQ，可先用 gpt-5.4-mini 控制成本；如果希望回答更自然、更稳，可以升级到 gpt-5.5。

接入方式

按投入和能力来分，网站 Chat Box 一般有下面三种接法：

方式是否需要后端适用场景建议
第三方客服脚本不需要人工客服、留言收集、快速上线最快
前端聊天框 + 固定回复可选站内引导、简单 FAQ过渡方案
前端聊天框 + SSOW API需要AI 客服、文档助手、产品问答推荐

不要把 API Key 写进前端

只要你的 Chat Box 需要请求模型，浏览器里都不应该直接出现 sk- 开头的密钥。即便代码混淆，也无法阻止被拿到。

嵌入脚本版

建议先把前端聊天浮窗放进页面，确认交互没问题，再去接后端。对于静态站，通常就是把下面这段放到 </body> 前。

chatbox.htmlhtml
<div id="chat-widget" style="position:fixed;right:24px;bottom:24px;z-index:9999;">
  <button id="chat-toggle">Chat</button>
  <div id="chat-panel" hidden>
    <div id="chat-messages"></div>
    <form id="chat-form">
      <input id="chat-input" placeholder="请输入你的问题" />
      <button type="submit">发送</button>
    </form>
  </div>
</div>

<script>
const toggle = document.getElementById('chat-toggle');
const panel = document.getElementById('chat-panel');
const form = document.getElementById('chat-form');

toggle.addEventListener('click', function () {
  panel.hidden = !panel.hidden;
});

form.addEventListener('submit', function (event) {
  event.preventDefault();
  // 下一步再把这里接到 /api/chat
});
</script>

先分两步做

第一步只做聊天框 UI 和开关逻辑；第二步再把提交事件改成请求你自己的 /api/chat。这样更容易排查是前端问题还是接口问题。

API 对接版

当前端聊天框准备好后，推荐在网站后端增加一个代理接口，由它去调用 SSOW 的 OpenAI 兼容聊天接口：

server.jsnode
import express from 'express';

const app = express();
app.use(express.json());

app.post('/api/chat', async (req, res) => {
  const messages = Array.isArray(req.body.messages) ? req.body.messages : [];

  const response = await fetch('https://token.ssow.org/v1/chat/completions', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': 'Bearer ' + process.env.SSOW_API_KEY
    },
    body: JSON.stringify({
      model: 'gpt-5.4-mini',
      temperature: 0.3,
      messages: [
        {
          role: 'system',
          content: '你是网站客服助手，只回答与本站产品、价格、文档和注册流程有关的问题。'
        },
        ...messages
      ]
    })
  });

  const data = await response.json();
  const reply = data.choices?.[0]?.message?.content ?? '暂时没有拿到模型回复';

  res.json({ reply });
});

app.listen(3000);

环境变量

把 SSOW 的 GPT 分组密钥放到服务端环境变量里：

.envbash
SSOW_API_KEY=sk-xxxxxxxxxxxxxxxx

不要让前端直连 SSOW

除了密钥泄露风险，浏览器跨域、限流、业务鉴权、日志审计也都更难控制。网站 Chat Bot 最好统一走你自己的后端。

AI Chat Bot

当前端聊天框和后端代理都准备好后，只需要把发送事件改成请求 /api/chat 即可。

chatbox.jsjavascript
const form = document.getElementById('chat-form');
const input = document.getElementById('chat-input');
const messages = [];

form.addEventListener('submit', async function (event) {
  event.preventDefault();
  const content = input.value.trim();
  if (!content) return;

  messages.push({ role: 'user', content });
  input.value = '';

  const response = await fetch('/api/chat', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ messages })
  });

  const data = await response.json();
  messages.push({ role: 'assistant', content: data.reply });
});

推荐模型

场景推荐模型说明
FAQ / 售前咨询gpt-5.4-mini成本更低，适合高频访问和简单问答。
产品顾问 / 深一点的解释gpt-5.5回复更自然，复杂问题更稳。
长文档说明 / 复杂流程解释claude-sonnet-4-6适合长上下文，但建议同样走后端代理。

想让答案更像你的业务团队

建议在后端加一层 system prompt，明确限制回答范围、语气、联系方式和升级路径；如果后续要做得更好，再引入 FAQ 检索、知识库或页面上下文。

常见问题

浏览器提示 CORS 或请求失败

大多数情况下是因为前端直接请求了模型接口。改成前端请求你自己的 /api/chat，由后端再去请求 SSOW，通常就能解决。

返回 401 / Unauthorized

检查后端环境变量里的 SSOW_API_KEY 是否正确，确认你使用的是 GPT 分组令牌，并且请求头里确实带了 Authorization: Bearer ...。

回复容易跑题

把 temperature 降低到 0.2 ~ 0.4，同时在 system prompt 里明确写清楚“只回答本站相关问题，不知道就引导联系客服”。

首条回复太慢

先换成 gpt-5.4-mini，并限制上下文长度。对普通官网客服来说，不需要把整段历史对话无限累积地发给模型。

用 curl 快速排查

curlbash
curl https://token.ssow.org/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $SSOW_API_KEY" \
  -d '{
    "model": "gpt-5.4-mini",
    "messages": [{"role": "user", "content": "ping"}]
  }'

如果这个请求能返回正常 JSON，而你的网站不行，问题一般就在你自己的后端转发、CORS 配置或前端请求逻辑上。

相关资源

SSOW 控制台

创建 GPT 分组 API Key，查看余额与调用记录

OpenAI Platform Docs

查看兼容的聊天请求格式、消息结构和参数说明

Tawk.to

如果你只想快速上线人工客服，也可以先用成熟的第三方客服脚本