使用传习社自部署的 DeepSeek¶

本文介绍如何在校园内网中，使用 CC Switch 配置传习社自部署的 DeepSeek，并接入 pi、DeepSeek Harness（dsh）和 OpenAI Codex。本文的配置路径不同：pi 和 Codex 通过 CC Switch 管理，dsh 在自己的 Web UI 中配置。其他支持 OpenAI-compatible API 的 harness 可以参照文末模板接入。

内部服务说明

本文包含传习社内网服务地址，只适用于能够访问校园内网的成员。部署到文档站前，请先确认站点的访问控制和搜索索引策略，不要把本文当作公开互联网教程发布。

先保护好 API Key

本文中的 你的_API_Key、sk-... 都是占位符。真实 Key 不要出现在截图、Git 仓库、公开脚本、群聊或 issue 中。怀疑泄露时，立即在 New API 中撤销旧 Key 并重新生成。

你将完成什么¶

完成本文后，你应该能够：

注册并登录传习社 New API；
完成实名核验并申请额度；
创建自己的 API Key；
安装 CC Switch 和至少一个 coding harness；
在 CC Switch 中配置 pi 和 codex；
在 dsh 自己的 Web UI 中添加自定义 OpenAI-compatible 提供方；
使用对应工具的内置测试或最小对话确认配置有效；
在 harness 中发送一条最小测试消息。

本文只围绕一个模型展开：

模型：deepseek-v4-flash

模型列表可能随服务端调整。若 CC Switch 或 dsh 的测试结果与本文不一致，以 New API 当前实际提供的模型列表和老师通知为准。

先理解四个概念¶

New API：传习社提供的统一模型服务入口，负责账号、Key、额度和请求转发。
OpenAI-compatible API：一种常见的 API 调用格式。很多 coding harness 虽然功能不同，但都能使用这种格式的服务。
harness：承载 coding agent 工作流的工具。本文中的例子是 pi、dsh 和 codex。
CC Switch：跨平台桌面应用，用图形界面管理 pi、Codex 等 harness 的供应商配置，避免手动编辑多个配置文件。dsh 不走 CC Switch，而是在自己的 Web UI 中配置。

整体关系如下：

flowchart LR
    U[同学的电脑]
    C[CC Switch]
    P[pi 配置]
    X[codex 配置]
    D[dsh Web UI]
    H[pi / dsh / codex]
    A[New API\n10.223.24.16:3000/v1]
    M[deepseek-v4-flash]

    U --> C
    C --> P
    C --> X
    U --> D
    P --> H
    D --> H
    X --> H
    H --> A
    A --> M

这里的三个 harness 配置入口不同：CC Switch 管理 pi 和 Codex，dsh 自己管理模型和提供方配置。不要假设修改一个配置后其他工具也会自动更新。

开始前：账号、内网和额度¶

1. 确认自己在校园内网¶

本文默认你已经连接到可以访问传习社服务的校园内网。先在浏览器打开：

http://10.223.24.16:3000

如果页面打不开，先处理网络问题，不要继续配置 CC Switch。常见原因包括：

当前不在校园网或没有连接对应网络；
使用了只能访问公网的网络环境；
本机代理、VPN 或防火墙拦截了内网地址；
服务临时维护。

2. 注册 New API 账号¶

在浏览器打开上面的地址，自行注册并登录账号。账号注册和登录由 New API 页面完成，CC Switch 不负责创建账号。

完成实名核验后，联系老师为账号发放额度。没有可用额度时，即使 API Key 和地址填写正确，也可能无法完成模型测试。

3. 创建自己的 API Key¶

额度生效后，在 New API 的个人设置或令牌页面创建 API Key，并立即复制保存。创建 Key 时注意：

每位同学使用自己的 Key，不要共用他人的 Key；
不要把 Key 发给老师以外的其他人；
不要把 Key 提交到 Git；
不要把完整 Key 放入截图；
Key 泄露后，立即撤销并重新生成。

安装 CC Switch¶

CC Switch 是基于 Tauri 构建的跨平台桌面应用，支持 Windows、macOS 和 Linux。三种系统的主界面和配置逻辑基本一致，本文只使用一套界面截图作为示例；下载的安装包和安装步骤则按系统选择。

下载¶

请从 CC Switch 的官方发布页下载最新版：

确认当前构建是否支持目标 harness

CC Switch 的官方版本会随时间调整支持的应用列表；本文以你们实际使用的构建中能够看到 pi 和 codex 为前提。安装最新版后，如果某个 harness 没有出现在应用列表中，不要把其他工具的配置强行套用过来，应先确认该版本是否提供对应适配，或使用传习社提供的兼容构建。dsh 不依赖 CC Switch。

本文不锁定 CC Switch 版本。最新版的按钮名称、布局和支持的应用可能与截图略有不同，请按以下几个概念寻找对应字段：

供应商 / Provider、API Key、Base URL、Model、测试 / Test、启用 / Activate。

按系统安装¶

Windows¶

下载 Windows 安装包（通常为 .msi），按安装向导完成安装。也可以使用官方发布页提供的绿色版压缩包。

系统要求和安装包名称以发布页为准。安装完成后，从开始菜单或安装目录启动 CC Switch。

macOS¶

下载 .dmg 文件，将 CC Switch 拖入 Applications（应用程序）目录后启动。也可以按照 CC Switch 官方说明使用 Homebrew：

brew install --cask cc-switch

Linux¶

根据发行版选择 .deb、.rpm 或 AppImage。使用 AppImage 时，可能需要先赋予执行权限：

chmod +x CC-Switch-*.AppImage
./CC-Switch-*.AppImage

Linux 桌面环境、Wayland 和显卡驱动差异较大。如果窗口可以打开但内容区无法点击，优先查看 CC Switch 发布页的 Linux 平台说明，不要重复安装服务端。

安装 coding harness¶

CC Switch 管理的是 pi 和 Codex 的配置，不一定替你安装 harness；dsh 则需要在自己的 Web UI 中配置模型。先安装要使用的工具，再按各自章节完成配置。

以下命令只负责安装和确认命令可用，不负责填写 API 地址或 API Key。不同系统可能需要先安装 Node.js；请以各工具的官方文档为准。

pi¶

官方项目：https://pi.dev/
npm 包：https://www.npmjs.com/package/@earendil-works/pi-coding-agent

安装：

npm install -g --ignore-scripts @earendil-works/pi-coding-agent

确认安装：

pi --version

DeepSeek Harness（dsh）¶

官方项目：https://github.com/deepseek-ai/deepseek-harness
官方文档：https://deepseek-harness.github.io/deepseek-harness/

安装：

npm install -g @deepseek-ai/dsh

确认安装：

dsh --version

DeepSeek Harness 仍在快速迭代。若最新版的安装方式或配置入口发生变化，以官方仓库和文档为准。

OpenAI Codex¶

官方项目：https://github.com/openai/codex
官方文档：https://developers.openai.com/codex/

安装：

npm install -g @openai/codex

确认安装：

codex --version

如果系统找不到 npm，先安装 Node.js，再重新执行对应命令。Windows 用户可以使用 PowerShell、Windows Terminal 或 Git Bash；安装完成后重新打开终端，让 PATH 更新生效。

配置字段¶

只允许使用 Chat Completions 端点

传习社 New API 这里只允许使用 OpenAI Chat Completions 协议。不要选择 Responses API、Anthropic Messages 或其他协议。客户端的 Base URL 统一填写 http://10.223.24.16:3000/v1，实际对话请求应发送到 /v1/chat/completions。

pi 和 Codex（通过 CC Switch）¶

在 CC Switch 中配置 pi 或 Codex 时，使用下面三项值：

字段	填写内容
Base URL	`http://10.223.24.16:3000/v1`
API Key	你自己创建的 API Key
Model	`deepseek-v4-flash`

dsh（通过自己的 Web UI）¶

dsh 的字段含义相同，但不在 CC Switch 中填写。打开 dsh 后进入 Settings → Models，添加自定义提供方：

字段	填写内容
Provider ID	例如 `cxstudio`，使用小写、稳定且唯一的 ID
Display Name	例如 `传习社 DeepSeek`
Base URL	`http://10.223.24.16:3000/v1`
API Protocol	`openai-completions`
API Key	你自己创建的 API Key
Model ID	`deepseek-v4-flash`

保存后，在模型选择器中选择刚刚添加的模型。dsh 的 API Key 由 dsh 自己管理，不要为了让 CC Switch 接管它而手动修改 dsh 的配置文件。

`/v1` 应该写在哪里？¶

如果字段名称是 Base URL、API Base URL 或 OpenAI Base URL，填写：

http://10.223.24.16:3000/v1

如果某个版本的 CC Switch 明确把字段定义为“服务器地址”，并注明会自动追加 /v1，才填写不带 /v1 的地址。不要根据猜测重复追加路径。

在 CC Switch 中配置 pi¶

打开 CC Switch，在应用或 harness 列表中选择 pi。
选择添加供应商、自定义供应商或同等含义的入口。
将供应商名称设为容易识别的名称，例如：传习社 DeepSeek。
如果需要选择协议，必须选择 OpenAI Chat Completions、OpenAI Completions 或界面中含义相同的选项。不要选择 Responses API、Anthropic Messages 或其他协议。
填写以下内容：

Base URL: http://10.223.24.16:3000/v1
API Key: 你的_API_Key
Model: deepseek-v4-flash

保存配置，并启用这份 pi 配置。
使用 CC Switch 的测试、模型检查或连接测试功能进行验证。
测试通过后，关闭已经打开的 pi 终端，再重新启动 pi。
发送最小测试消息：

请只回复：DeepSeek 接入成功。
不要调用工具，不要修改文件。

截图建议

pi 的截图只需要展示应用选择、Base URL、API Key 字段和 Model 字段。API Key 必须完全打码；按钮位置随 CC Switch 版本变化，不要在截图说明中写死坐标。

在 dsh 中自行配置¶

dsh 不通过 CC Switch 管理模型配置，需要在 dsh 自己的 Web UI 中添加自定义提供方。

启动 dsh：

dsh web

打开 dsh 显示的本地 Web UI 地址。
进入 Settings → Models。
选择 Add custom provider。
选择 OpenAI Chat Completions 协议；dsh 中对应的协议值是 openai-completions。不要选择 openai-responses 或 anthropic-messages。
填写：

Provider ID: cxstudio
Display Name: 传习社 DeepSeek
Base URL: http://10.223.24.16:3000/v1
API Protocol: openai-completions
API Key: 你的_API_Key
Model ID: deepseek-v4-flash

保存自定义提供方和模型。
在模型选择器中选中 deepseek-v4-flash。
在 dsh 中发送最小测试消息：

请只回复：DeepSeek 接入成功。
不要调用工具，不要修改文件。

dsh 的模型配置会在下一次请求时生效，通常不需要重启 Web UI。若使用的是与本文不同版本的 dsh，优先以其官方文档中的菜单名称和配置字段为准。

dsh 的模型探测

dsh 的自定义提供方页面可以尝试获取可用模型；如果探测失败，直接手动填写 deepseek-v4-flash 即可。探测功能只是便利工具，不是配置成功的必要条件。

dsh 不使用 CC Switch

不要在 CC Switch 中寻找 dsh 配置，也不要把 pi 或 Codex 的配置文件复制给 dsh。dsh 使用自己的模型页和配置存储；API Key 也由 dsh 自己保存。

在 CC Switch 中配置 Codex¶

在 CC Switch 中选择 Codex。
单独创建 Codex 的供应商配置。
如果界面提供多个 Codex 协议选项，必须选择支持 OpenAI Chat Completions 和自定义 Base URL 的选项。不要选择 Responses API、OAuth 或 Anthropic 协议。
填写：

Base URL: http://10.223.24.16:3000/v1
API Key: 你的_API_Key
Model: deepseek-v4-flash

保存并启用 Codex 配置。
使用 CC Switch 内置测试确认配置可用。
完全退出已经运行的 Codex 进程，再重新打开终端启动：

codex

发送最小测试消息：

请只回复：DeepSeek 接入成功。
不要调用工具，不要修改文件。

关于 Codex 的协议兼容性

Codex 的不同版本和配置模式可能使用不同的请求协议。本文只允许使用 CC Switch 中支持自定义 Base URL 的 Chat Completions 配置入口；如果测试失败，先确认当前配置没有使用 Responses API、官方登录或 OAuth 模式。

其他 harness 的接入模板¶

如果某个 harness 支持 OpenAI Chat Completions API，可以按下面的字段寻找配置入口：

Provider / 供应商：自定义或 OpenAI Chat Completions
Base URL：http://10.223.24.16:3000/v1
API Key：你的_API_Key
Model：deepseek-v4-flash

不要选择 Responses API 或 Anthropic Messages API。

判断是否接入成功的最低标准是：

如果使用 CC Switch，配置能保存并通过内置测试；
如果使用 dsh，自己的模型页能保存提供方并选中该模型；
harness 重启或配置生效后能发起请求；
harness 返回：DeepSeek 接入成功。

如果 CC Switch 当前版本没有该 harness 的专属配置入口，不要把“能填写字段”误认为“已经兼容”。先查该 harness 的官方文档，确认它是否支持自定义 OpenAI-compatible Base URL。

常见排错¶

排错时按层次进行，不要一上来反复生成 API Key。

现象	所属层次	优先检查	处理方式
浏览器打不开 New API	网络层	是否在校园内网、地址是否正确	先恢复内网访问；确认 `10.223.24.16:3000` 能打开
CC Switch 无法连接	网络层 / CC Switch 层	Base URL 是否填错、系统代理是否拦截	确认填写的是 `http://10.223.24.16:3000/v1`；检查系统代理和防火墙
`401 Unauthorized`	API 层	API Key 是否复制完整、是否多了空格	重新复制个人 Key；不要在 Key 前后加入引号或空格
`403 Forbidden`	账号 / 权限层	账号是否完成核验、额度是否已发放	联系老师确认额度状态；不要用他人 Key
`404 Not Found`	地址层	`/v1` 是否缺失或重复	Base URL 通常使用带 `/v1` 的地址；检查 CC Switch 是否会自动追加路径
`429 Too Many Requests`	额度 / 服务层	额度、并发和服务限流	暂停重试，确认额度和服务状态；不要用多个 Key 绕过限制
模型不存在	模型层	Model 是否填写为 `deepseek-v4-flash`	修正模型名；以 CC Switch 测试返回的模型列表为准
CC Switch 测试成功，pi/Codex 失败	harness 层	是否启用了错误配置、是否重启	确认配置是对应 harness 的独立配置；完全退出后重新启动
dsh 模型页保存成功但请求失败	dsh 层	Provider ID、协议、Base URL、模型 ID	确认协议为 `openai-completions`，模型 ID 为 `deepseek-v4-flash`；再检查 Key 和额度
修改后仍使用旧配置	harness 层	旧终端或旧进程是否仍在运行	关闭旧进程，重新打开终端；不要直接编辑 CC Switch 管理的文件
测试能返回，但工具调用异常	功能兼容性层	harness、协议和模型能力	先以文本回复作为接入成功标准；工具调用另行确认兼容性

CC Switch 内置测试失败时的排查顺序¶

在浏览器确认 New API 首页可以打开；
检查当前电脑是否仍在校园内网；
检查 Base URL 是否为 http://10.223.24.16:3000/v1；
检查 API Key 是否为自己的 Key，且没有多余空格；
检查账号是否已经由老师发放额度；
检查 Model 是否为 deepseek-v4-flash；
重新保存配置后再次测试；
仍然失败时，再使用本文“手动 API 诊断”章节。

对于 dsh，优先在 Settings → Models 中重新检查自定义提供方的协议和模型 ID；不要回到 CC Switch 中排查 dsh。

手动 API 诊断（高级）¶

普通使用不需要执行本节。只有在 CC Switch 内置测试失败，且需要区分“服务问题”和“客户端问题”时，才使用手动请求。

macOS / Linux：检查模型列表¶

curl "http://10.223.24.16:3000/v1/models" \
  -H "Authorization: Bearer 你的_API_Key"

返回结果中应能找到 deepseek-v4-flash。如果请求超时，优先排查网络；如果返回 401、403 或 429，按上面的排错表处理。

macOS / Linux：发送最小对话请求¶

curl "http://10.223.24.16:3000/v1/chat/completions" \
  -H "Authorization: Bearer 你的_API_Key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "deepseek-v4-flash",
    "messages": [
      {"role": "user", "content": "请只回复：API 测试成功。"}
    ]
  }'

Windows PowerShell：检查模型列表¶

$headers = @{ Authorization = "Bearer 你的_API_Key" }
Invoke-RestMethod `
  -Uri "http://10.223.24.16:3000/v1/models" `
  -Headers $headers `
  -Method Get

Windows PowerShell：发送最小对话请求¶

$headers = @{
  Authorization = "Bearer 你的_API_Key"
}
$body = @{
  model = "deepseek-v4-flash"
  messages = @(
    @{
      role = "user"
      content = "请只回复：API 测试成功。"
    }
  )
} | ConvertTo-Json -Depth 4

Invoke-RestMethod `
  -Uri "http://10.223.24.16:3000/v1/chat/completions" `
  -Headers $headers `
  -Method Post `
  -ContentType "application/json" `
  -Body $body

如果手动请求成功而 CC Switch 测试失败，说明服务和 Key 大概率正常，应继续检查 CC Switch 的配置类型、字段映射或当前版本兼容性。

安全清单¶

离开电脑前和分享截图前，按下面的清单检查一次：

[ ] 截图中的 API Key 已完全打码；
[ ] API Key 没有提交到 Git；
[ ] 没有把 Key 写进公开 .env、脚本或 README；
[ ] 没有在群聊、issue 或论坛粘贴完整 Key；
[ ] 没有使用他人的 Key；
[ ] 泄露后已经撤销并重新生成；
[ ] 没有为了绕过限流或额度限制创建、借用多个账号；
[ ] 公开发布本文前，已确认文档站的访问控制。

使用传习社自部署的 DeepSeek¶

你将完成什么¶

先理解四个概念¶

开始前：账号、内网和额度¶

1. 确认自己在校园内网¶

2. 注册 New API 账号¶

3. 创建自己的 API Key¶

安装 CC Switch¶

下载¶

按系统安装¶

Windows¶

macOS¶

Linux¶

安装 coding harness¶

pi¶

DeepSeek Harness（dsh）¶

OpenAI Codex¶

配置字段¶

pi 和 Codex（通过 CC Switch）¶

dsh（通过自己的 Web UI）¶

/v1 应该写在哪里？¶

在 CC Switch 中配置 pi¶

在 dsh 中自行配置¶

在 CC Switch 中配置 Codex¶

其他 harness 的接入模板¶

常见排错¶

CC Switch 内置测试失败时的排查顺序¶

手动 API 诊断（高级）¶

macOS / Linux：检查模型列表¶

macOS / Linux：发送最小对话请求¶

Windows PowerShell：检查模型列表¶

Windows PowerShell：发送最小对话请求¶

安全清单¶

相关链接¶

`/v1` 应该写在哪里？¶