Skip to main content

接入第三方

在开始之前，先弄清楚两个名词，后文会反复出现：

  • 1Panel AI 网关：部署在你（或管理员）服务器上的"模型中转站"。它把各种大模型统一包装成一个标准接口，你在客户端里填上它的地址和密钥，就能用上网关里的模型。
  • API Key：可以理解为"门禁卡"。客户端要访问网关，必须出示这张卡；没有它或者卡号填错，请求会被拒绝。

整个接入流程只有三步：① 下载并安装客户端 → ② 在网关管理端拿到 API Key → ③ 在客户端里填好配置。下面逐个客户端讲解。

在动手前，请先向管理员确认两件事（建议拿张纸记下来）：

  1. 接口地址（Base URL）：例如 https://1router.1panel.cn/v1，注意末尾的 /v1 不能少。
  2. 模型名称：管理员在网关里给你开通的模型标识（例如 1Panel-Auto），配置时必须一字不差。

1 准备工作：获取 API Key（三个客户端通用）​

不管你用哪个客户端，都需要先在 1Panel AI 网关管理端创建属于自己的 API Key。如果你已经做过这一步并保存了 Key，可以跳到对应客户端的章节。

首先进入模型广场：登录管理端后，默认进入「模型广场」页面。在这里你能看到网关已接入的所有可用模型、统一的接入地址，以及每个模型的名称与类型。后续客户端配置要用到的模型名称和接入地址，都能在这一页找到（配置时需一字不差）。

模型广场
图 1 模型广场

然后创建 API Key：进入「API Key 管理」页面，为自己创建新的 API Key。Key 仅在创建时完整显示一次，请务必立即复制保存。

创建 API Key
图 2 创建 API Key

复制并妥善保管 API Key，避免泄露给他人。如 Key 遗忘或泄露，需在管理端重新生成并更新所有客户端配置。

复制 API Key
图 3 复制 API Key

2 接入 WorkBuddy​

2.1 下载并安装 WorkBuddy​

WorkBuddy 是一款 AI 办公桌面客户端，支持 Windows 和 macOS，双击安装包、像装普通软件一样下一步到底即可。

  • 官方下载页：https://www.workbuddy.cn/（打开网页后点击页面上的"立即下载"，按自己的电脑系统选择：Windows 选 Windows x64；Mac 电脑按芯片选 Apple 芯片（M 系列） 或 Intel 版本）
温馨提示

怎么知道自己的 Mac 是苹果芯片还是 Intel？点屏幕左上角苹果图标 →「关于本机」，"芯片"一栏写着 Apple Mx 就选 ARM64/Apple 芯片版，写着 Intel 就选 x64/Intel 版。

安装完成后打开 WorkBuddy，用页面上的入口登录账号，即可进行下面的模型配置。

2.2 配置自定义模型​

点击配置自定义模型：在客户端设置中找到「自定义模型」或「添加模型」入口。

配置自定义模型
图 4 配置自定义模型

提供商选择自定义：类型选择「自定义」或「OpenAI 兼容」，不要选择预设的 OpenAI 官方选项。

选择自定义提供商
图 5 选择自定义提供商

填入以下三项信息：

  • 接口地址（Base URL）：https://1router.1panel.cn/v1 （以管理员给你的地址为准）
  • API Key：第 1 步里复制的 API Key
  • 模型名称：管理员给你开通的模型名称

三者需完全一致。

填写接入配置
图 6 填写接入配置
注意

接口地址末尾的 /v1 路径不可省略，部分客户端会自动补全，但建议显式写入以避免请求失败。

2.3 保存并测试​

点击保存，选择刚才配置的模型进行测试：在模型列表中发送测试消息，验证请求是否正常返回。

保存并测试模型
图 7 保存并测试模型

3 接入 DeepSeek Harness​

3.1 下载并安装 DeepSeek Harness​

DeepSeek Harness 是 DeepSeek 官方开源的 Agent 运行工具，它不是"下载一个安装包"这么简单，需要先了解一下两种官方安装方式，任选其一：

  • 方式一：命令行快速启动（推荐）。先安装 Node.js（去官网 https://nodejs.org 下载 LTS 版本，一路下一步安装即可），然后在终端（Windows 打开 PowerShell，Mac 打开"终端"）里输入下面这行命令回车，等待启动完成： 
    npx @deepseek-ai/dsh web
    启动成功后，终端会显示一个本地网址（例如 http://127.0.0.1:3080），用浏览器打开这个网址，就是 DeepSeek Harness 的操作界面。
  • 方式二：源码安装（适合有开发经验的用户）： 
    git clone https://github.com/deepseek-ai/deepseek-harness
    然后按照仓库里的说明完成安装。
  • 官方渠道入口：官网 https://www.deepseek.com（DeepSeek 官网首页可找到 Harness 相关入口）；GitHub 仓库 https://github.com/deepseek-ai/deepseek-harness。
认准官方渠道

网上存在仿冒 DeepSeek / DeepSeek Harness 的网站和账号。请只通过上述官方地址下载，任何"收费入群""收费激活"都是假冒行为。

3.2 配置接入 1Panel AI 网关​

进入 DeepSeek Harness（浏览器打开的界面），点击设置、模型、添加自定义提供方。

添加自定义提供方
图 8 添加自定义提供方

填写提供方配置：名称可以随意起（仅用于自己识别）。

API 地址填 https://1router.1panel.cn/v1（末尾 /v1 不可省略）。

API 密钥填第 1 步里复制的 API Key，API 协议保持默认即可。

填好后可以点击"获取可用"拉取模型列表；若获取不了，也可以点击"添加"手动填写模型名称（名称需与管理员开通的模型名称完全一致）。

填写提供方配置
图 9 填写提供方配置

3.3 选择模型并测试​

选择配置好的模型进行测试：保存后在底部输入框左侧的提供商下拉菜单中选择刚添加的提供方，发送消息验证连接。

选择模型并测试
图 10 选择模型并测试

4 接入 codex​

4.1 下载并安装 codex（Codex CLI）​

Codex CLI 是 OpenAI 推出的终端编程助手——没有窗口界面，在命令行（终端）里敲 codex 命令使用。安装分两步：

第一步，安装 Node.js（版本建议 22 及以上）。去 Node.js 官网 https://nodejs.org 下载 LTS 版本，安装时保持默认选项即可。装完打开终端输入 node -v，能显示版本号就说明装好了。

第二步，安装 Codex CLI。打开终端（Windows 用 PowerShell，Mac 用"终端"），输入：

npm install -g @openai/codex
温馨提示
  • 包名必须是 @openai/codex，注意前面有 @openai/，不要只输 codex，那是一个不相关的旧包。
  • 如果下载很慢或超时，可以先换国内镜像源再装：npm config set registry1 https://registry.npmmirror.com

安装完输入 codex --version，能显示版本号即成功。

4.2 CC Switch 配置​

Codex CLI 本身不提供可视化的供应商管理界面，直接修改 ~/.codex/config.toml 的方式门槛较高。这里借助 CC Switch 这一小工具完成配置：它负责管理 Codex 的供应商配置，并把请求路由到 1Panel AI 网关，无需手工编辑配置文件。

CC Switch 下载地址（GitHub Releases 发布页）：https://github.com/farion1231/cc-switch/releases/latest

  • Windows：下载 CC-Switch-vX.X.X-Windows.msi 安装包，双击按向导安装
  • macOS：下载 CC-Switch-vX.X.X-macOS.zip，解压后把应用拖入"应用程序"文件夹（首次打开若提示"未知开发者"，前往「系统设置 → 隐私与安全性」点击「仍要打开」）

首先下载并安装 CC Switch，安装完成后打开软件，进入供应商管理界面，点击右上角「添加」按钮，新建一个供应商配置。

点击添加
图 11 点击添加

在弹出的表单中选择「自定义配置」，并填写以下信息：

  • API Key：粘贴在 1Panel AI 网关管理端创建的 API Key
  • API 请求地址：https://1router.1panel.cn/v1（注意末尾的 /v1 不可省略）

同时打开「本地路由映射」开关。该功能会在本机启动一个代理地址，Codex 的请求先发往本地代理，再由 CC Switch 转发到 1Panel AI 网关，从而绕开 Codex 对官方接口地址的限制。

填写配置并启用路由
图 12 填写配置并启用路由

点击「获取模型列表」，CC Switch 会通过网关的 /v1/models 接口拉取当前可用的模型。在返回的列表中选择要使用的模型（或手动添加，名称需与管理端模型映射中的请求模型名称完全一致），确认无误后点击「添加」按钮保存该供应商配置。

获取模型列表并提交
图 13 获取模型列表并提交

回到 CC Switch 的开始界面，在供应商列表中选中刚创建的配置，点击「启动」，CC Switch 会将本地路由代理与 Codex 配置一并写入。之后重启 codex（退出正在运行的 Codex CLI 进程后重新启动），使新配置生效。

重启 codex
图 14 重启 codex

4.3 发起测试对话​

在 codex 中发起一次对话测试：选择映射到 1Panel AI 网关的模型（如 1Panel-Auto），发送一条简单消息。若能正常返回回复，说明整条链路（codex → CC Switch 本地路由 → 1Panel AI 网关 → 上游模型）已经打通。

codex 测试对话
图 15 codex 测试对话

5 常见问题排查（FAQ）​

配置完成后测试如果不通，按下面的对照表排查，基本都能解决：

报错现象大概率原因解决办法
401 / 403API Key 无效、复制不完整（少了开头或结尾字符）、已过期回管理端确认 Key 有效，重新复制粘贴一遍，注意不要带空格
404接口地址或模型名称填错检查 Base URL 末尾是否有 /v1；模型名称与管理员开通的是否一字不差
连接超时 / 无法访问网络不通、地址不对换个浏览器访问 Base URL 确认可达；确认电脑没有开启拦截流量的代理软件
能连通但没有回复 / 模型列表为空该模型未分配给你的账号联系管理员确认模型已加入你的用户组