自定义提供商让 PandaNpc 可以使用您控制的 API 账户、私有网关或本地模型端点。这通常称为 BYOK：自带密钥。当您需要内置目录之外的模型、提供商侧计费、内部代理、Ollama、LM Studio 或自托管的 OpenAI 兼容服务时，它非常有用。
对于受支持的直接聊天，PandaNpc 会将请求发送到您配置的端点，而不是替换内置模型。您的上游提供商仍然控制定价、数据保留、速率限制、模型可用性和可接受使用政策。
前提条件和安全边界
在添加提供商之前，请收集：
- 提供商的 API 密钥或本地身份验证令牌。
- 其 API 基础 URL，对于 OpenAI 兼容服务通常以
/v1结尾。 - API 接受的准确模型标识符。
- 如果您计划覆盖默认值，请记录文档中的上下文窗口和最大输出限制。
使用具有最低必要权限的专用密钥，并在提供商支持的情况下设置支出限额。切勿将密钥放入文档、聊天提示、截图、浏览器控制台输出或 Git 仓库中。
在 Web 浏览器中，直接请求受 CORS 限制。提供商必须允许来自 https://pandanpc.com 的请求。诸如 http://localhost:11434/v1 的基础 URL 指的是运行浏览器的计算机，而不一定是远程的 PandaPaw 机器。桌面应用可能更适合本地端点，因为它不受浏览器 CORS 的同样限制。
第 1 步：打开模型配置
登录 PandaNpc 并打开 模型配置。提供商和模型是单独的记录：提供商存储连接和身份验证详细信息，而每个模型存储发送到该连接的标识符和限制。
如果已出现官方提供商，请配置或复制它，而不是自行创建不同的协议。对于新的 OpenAI 兼容网关，请选择 添加提供商。
第 2 步：添加提供商
填写提供商表单：
| 字段 | 填写内容 | 示例或说明 |
|---|---|---|
| 显示名称 | 您可见的标签 | Company AI Gateway |
| 提供商 ID | 稳定的内部标识符 | company-openai |
| API Key | 用作持有者令牌的密钥 | 提供商颁发的值 |
| 基础 URL | API 根路径，不含 /chat/completions |
https://gateway.example.com/v1 |
| 协议 | 上游 API 格式 | 对于 OpenAI 兼容的聊天补全，选择 openai |
| 密钥 | 可选的第二个密钥 | 除非提供商要求，否则留空 |
| 组织 | 可选的组织标识符 | 仅当提供商要求时 |
| 项目 | 可选的项目标识符 | 仅当提供商要求时 |
| 支持内容数组 | 消息内容是否可以使用结构化数组 | 对于接受现代多模态消息内容的提供商，请保持启用 |
PandaNpc 会从基础 URL 中移除尾部斜杠，并为直接的 OpenAI 兼容聊天请求追加 /chat/completions。因此请输入：
https://api.example.com/v1而不是：
https://api.example.com/v1/chat/completions在添加模型之前，请先保存提供商。编辑现有提供商时，API Key 或密钥字段为空表示“保留已配置的值”；它不会将存储的密钥回显到表单中。
第 3 步：添加模型
在提供商下选择 添加模型 并填写以下字段：
| 字段 | 含义 | 示例 |
|---|---|---|
| 显示名称 | 人类可读的选择器标签 | My Coding Model |
| 模型值 | 准确的上游模型 ID | model-name-from-provider |
| 模型类型 | PandaNpc 功能/类别映射 | 从表单中选择一个当前值 |
| 提供商 | 上面创建的提供商记录 | Company AI Gateway |
| 上下文窗口 | 支持的令牌总数 | 使用提供商文档中的整数限制 |
| 最大令牌数 | 最大生成的输出令牌数 | 使用不超过提供商限制的正值 |
显示名称 可以更改而不影响 API 调用。模型值 不能根据营销名称猜测；请从提供商的 API 文档或模型列表端点复制。
如果不确定，请将上下文窗口和最大令牌数留空。保守的默认值比声明大于服务器支持的上下文窗口更安全。这些字段对 PandaCode 尤其重要，因为它们会影响压缩和输出预算。
常见端点示例
以下模式说明了 URL 格式；可用性和模型 ID 取决于您的安装或提供商账户：
| 服务类型 | 典型基础 URL | 说明 |
|---|---|---|
| OpenAI 兼容云 API | https://provider.example.com/v1 |
必须支持流式 Chat Completions 和持有者身份验证 |
| 查看计算机上的 Ollama | http://localhost:11434/v1 |
启动 Ollama 的 OpenAI 兼容端点；浏览器使用可能需要 CORS 配置 |
| 查看计算机上的 LM Studio | http://localhost:1234/v1 |
启动本地服务器并选择已加载的模型 ID |
| 私有网络网关 | https://ai.internal.example/v1 |
PandaNpc 客户端必须能够解析并访问该主机 |
不要假设所有标榜“OpenAI 兼容”的服务都实现了流式传输、工具调用、图像、推理字段或相同的错误响应。请测试您工作流所需的确切功能。
验证提供商和模型
在依赖该配置之前，请使用低成本、非敏感的提示进行验证：
- 在新对话中选择新模型。
- 发送
Reply with exactly: provider connected。 - 确认响应以流式方式返回，并且提供商仪表板记录了该请求。
- 发送简短的后续消息以验证对话历史记录。
- 如果您需要工具、图像或长上下文，请分别测试每项功能。
对于本地端点，请先在 PandaNpc 之外进行验证。通常可以使用以下命令获取 OpenAI 兼容模型列表：
curl http://localhost:11434/v1/models仅使用响应来确认可达性和模型 ID。不要将生产 API 密钥直接放入 shell 历史记录中。
将自定义模型与 PandaCode 结合使用
PandaCode 可以提供类似 Claude Code 的编码工作流，同时使用您选择的模型后端，包括 DeepSeek、Qwen、OpenAI 兼容网关或内部服务。配置提供商和模型后，请为相关的 PandaCode 连接或任务选择该模型。
模型必须支持编码引擎所需的交互模式。适用于普通聊天的提供商在工具调用、长时间运行的流或结构化内容方面仍可能失败。有关聊天模型与本地编码引擎之间的区别，请参阅 PandaNpc 支持的 AI 模型；有关远程引擎设置，请参阅 PandaPaw 安装和命令。
故障排除
`401` 或 `403` 身份验证错误
创建新的提供商密钥，确认其处于活动状态，然后重新输入。检查上游服务是否需要组织、项目或不同的身份验证方法。从编辑屏幕复制的掩码密钥不是原始密钥。
`404` 端点或模型未找到
从配置的基础 URL 中移除 /chat/completions，因为 PandaNpc 会追加它。确认 /v1 在需要时存在，并且模型值准确匹配上游模型 ID。提供商可能会对错误的 URL 和不可用的模型返回相同的 404。
浏览器报告网络或 CORS 错误
仅打开浏览器开发者控制台以识别被阻止的来源；请勿在其中粘贴密钥。配置提供商以允许 https://pandanpc.com，使用其 HTTPS 端点，或使用 PandaNpc 桌面应用。混合内容规则会阻止 HTTPS 页面调用某些纯 HTTP 端点。
无法访问本地 Ollama 或 LM Studio
确保服务器与发出请求的客户端运行在同一台计算机上，并监听配置的接口和端口。如果模型服务器运行在另一台计算机上，则 localhost 是错误的；请使用可访问的私有主机名或 IP，并在暴露服务之前确保其安全。
响应开始但停止或没有内容
确认 API 支持流式 Chat Completions 并发出标准的 data: 事件。减少最大令牌数，测试纯文本消息，并且仅在提供商文档说明其仅接受字符串内容时，才禁用结构化内容数组。
长会话在接近上下文限制时失败
将配置的上下文窗口降低到提供商实际支持的限额，并为输出、系统指令和工具结果预留空间。更改模型配置后，请启动新会话，以便新限制得到一致应用。
有关账户级配额和数据流详细信息，请阅读 PandaNpc 账户、套餐和 API 成本 和 隐私政策。