# protonkener 系统配置说明

更新：2026-09-08

## 平台简介

protonkener 为已开通账户提供统一模型入口、API 密钥管理、钱包与订阅计费、调用记录和本地 Adapter 配置。用户只使用自己的平台密钥，上游凭证由服务端管理。

### 三步开始

1. 联系管理员开通普通用户或代理商账户，使用登记手机号短信登录，首次登录设置密码。
2. 进入 API 密钥，确认钱包或订阅额度，创建独立应用密钥并选择允许模型。
3. 在 API 密钥页选择 Codex / Claude Code / API 或 Adapter 一键配置，按客户端对应说明接入。

### 入口

| 项目 | 说明 |
| --- | --- |
| 平台 | https://protonkener.com |
| 文档中心 | https://docs.protonkener.com |
| OpenAI 兼容 Base URL | https://protonkener.com/v1 |
| Claude Code Base URL | https://protonkener.com |

配置说明以本平台实际实现为准。模型可见不等于当前上游一定可用；实际权限取决于账户、密钥、套餐与模型状态。请勿将上游余额与自己的平台钱包余额混淆。

## 账户开通与安全

### 所有账户由管理员统一开通

数据库中不存在的手机号不能通过短信或密码登录，登录不会自动注册账户。超级管理员分别在普通用户、代理商菜单手动添加，开户通知发送给新账户登记手机号。

1. 首次使用：短信登录 → 设置个人密码 → 返回平台。
2. 已有密码：可以密码登录；忘记密码时使用登记手机号找回。
3. 账户暂停：现有登录与 API 调用停止，状态通知发给被操作用户。恢复后检查密钥是否需要重新启用。
4. 管理员权限与客户类型分开管理。代理商资格变更不应授予或撤销超级管理员登录身份。

### 保护凭证

每个应用创建独立 API Key。不要把密钥写进公开仓库、截图、共享文档或网页前端代码。泄露后立即停用并更换；删除旧密钥会影响依赖它的本地客户端凭证。

## API 密钥与权限

1. 进入 API 密钥 → 创建密钥，填写便于识别的名称和分组。
2. 选择钱包或订阅计费。订阅密钥绑定具体周期；开通新周期后创建并配置新周期密钥。
3. 选择允许模型，按需设置额度上限、有效期、IP 白名单和速率限制。
4. 复制平台密钥到客户端。连接检查用于验证认证和模型目录，不代表已经完成真实推理。

### 权限取交集

实际可调用模型是平台支持范围、已上架目录、密钥允许范围、订阅权限的交集。GET /v1/models 返回当前密钥可见模型。界面显示名称不能代替返回的精确 id，cl-、lp- 等路由前缀不要自行删除。

密钥额度上限是消费限制，不是充值。钱包赠送、现金余额和订阅额度分别记录；提高密钥上限不会自动增加账户可用额度。

## API 与 SDK

### 协议与认证

| 项目 | 说明 |
| --- | --- |
| GET /v1/models | 查询本密钥可用模型 |
| POST /v1/chat/completions | OpenAI Chat Completions |
| POST /v1/responses | OpenAI Responses，Codex 使用 |
| POST /v1/messages | Anthropic Messages，Claude Code 使用 |

使用 Authorization: Bearer YOUR_API_KEY；Messages 也支持 x-api-key。不同模型支持的协议不同，请在 API 密钥配置页选择对应客户端和模型。不要将 HAI 管理 Token 或登录验证码当成 API Key。

```
curl https://protonkener.com/v1/models \
  -H "Authorization: Bearer $PROTONKENER_API_KEY"
```

```
curl https://protonkener.com/v1/chat/completions \
  -H "Authorization: Bearer $PROTONKENER_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"model":"YOUR_MODEL_ID","messages":[{"role":"user","content":"你好"}],"stream":true}'
```

```
from openai import OpenAI
import os
client = OpenAI(api_key=os.environ['PROTONKENER_API_KEY'],
                base_url='https://protonkener.com/v1')
response = client.responses.create(model='YOUR_MODEL_ID', input='你好')
print(response.output_text)
```

将 YOUR_MODEL_ID 换成目录返回且支持当前协议的 id。流式响应使用 SSE，客户端需要持续读取直到结束；中途断开不代表上游没有产生费用。网关不是完整 OpenAI 或 Anthropic 全产品 API，文件、Batch、Realtime 等未列出的接口不在支持范围。

## Codex CLI

使用支持 Responses 协议的模型。在 API 密钥页选择 Codex CLI，可生成与你的模型选择对应的配置。下方示例需替换模型和密钥。

### 1. 合并配置

macOS / Linux：~/.codex/config.toml；Windows：%USERPROFILE%\.codex\config.toml。已有配置先备份，顶层字段放在 TOML 表段之前，同名 provider 不要重复定义。

```
model_provider = "protonkener"
model = "YOUR_MODEL_ID"

[model_providers.protonkener]
name = "protonkener"
base_url = "https://protonkener.com/v1"
env_key = "PROTONKENER_API_KEY"
wire_api = "responses"
```

### 2. 设置密钥并从同一终端启动

```
# macOS / Linux
export PROTONKENER_API_KEY='YOUR_API_KEY'
codex
```

```
# Windows PowerShell
$env:PROTONKENER_API_KEY = 'YOUR_API_KEY'
codex
```

上述环境变量仅对当前终端及其子进程生效。重开终端需要重新设置或使用系统安全的环境变量管理。先测试简单文本，再测试文件读取与工具调用。Codex 桌面应用的 provider 支持与 CLI 可能不同，本节不等同于已完成桌面端验证。

## Claude Code

使用具备 Anthropic Messages 协议的 Claude 模型。Base URL 填站点根地址，客户端自行追加 /v1/messages，避免出现 /v1/v1/messages。

### 用户配置

将以下 env 合并到 ~/.claude/settings.json，Windows 对应 %USERPROFILE%\.claude\settings.json。替换密钥和精确模型 id；不要把真实密钥保存到项目共享配置。

```
{
  "env": {
    "ANTHROPIC_BASE_URL": "https://protonkener.com",
    "ANTHROPIC_AUTH_TOKEN": "YOUR_API_KEY",
    "ANTHROPIC_MODEL": "YOUR_CLAUDE_MODEL_ID",
    "CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY": "1"
  }
}
```

1. 重启 Claude Code，通过 /status 核对服务地址，通过 /model 查看可用 Claude 模型。
2. 如果终端已有 ANTHROPIC_BASE_URL、ANTHROPIC_API_KEY 或其他认证配置，排查是否与用户配置冲突。
3. 先验证一轮文本与工具调用。1M 上下文、推理档位与测试性功能取决于模型和上游能力，不能仅靠名称保证。

网关保留 Messages 请求的 anthropic-version、anthropic-beta 以及 beta 查询开关。未单独实现 count_tokens；客户端是否降级取决于版本。不要用成功返回模型列表来判断所有 Claude Code 功能均兼容。

## Adapter 一键配置

Adapter 面向 CodeBuddy / WorkBuddy 等本地客户端。它把客户端协议、模型目录和平台个人密钥连接起来。Codex CLI 与 Claude Code 可按前两节直连，无需强制安装本地 Adapter。

### 安装步骤

1. 先在平台创建有效密钥，再打开 API 密钥 → Adapter 一键配置。
2. 选择客户端与密钥，下载当前完整安装包及一次性 setup 配置文件。不要把 setup 文件共享给其他用户。
3. 按页面提示在目标客户端安装技能，使用 setup 文件绝对路径运行安装器。Windows 路径有空格时必须加引号。
4. 安装器交换一次性授权，生成本机凭证，写入客户端模型配置与登录启动项。成功后按提示重启客户端。
5. 选择 pt/ 前缀的模型，发送一条简单消息，再验证工具调用。

### 授权和本地运行

setup 授权有效期为 60 分钟，并且只能兑换一次。已用或过期时重新从平台生成；短时安装重试需要沿用同一安装凭证，不能复制到另一台机器。客户端凭证继承源密钥权限，源密钥停用、到期或账户暂停会影响本地调用。

本地代理必须持续运行。安装文件复制成功不代表代理已监听，也不代表授权兑换成功。受限沙箱可能在命令结束时回收后台进程，应在用户真实桌面会话按安装说明启动，并核对登录自启动。

### 升级与排障

1. 升级使用平台最新完整包，避免混用旧安装器和新运行时。
2. 授权失败：重新生成 setup 文件；检查系统时间和网络。
3. 模型存在但 502：检查代理健康、本地日志及平台请求记录，再核对模型协议。
4. 源密钥更换：重新生成对应配置，不能仅改模型名称。
5. 分享日志前移除密钥、setup 授权和个人信息。

## 模型定价与支持范围

平台只开放当前选定模型。具体可调用 id、协议、价格与上架状态，以登录后的模型定价和 GET /v1/models 为准。未同步到的目标型号不会伪造上线。

| 项目 | 说明 |
| --- | --- |
| Claude | Sonnet 5（含 1M 规格）、Opus 4.8 / 4.7 / 4.6（含 1M 规格）、Sonnet 4.6 的 1M 规格、Opus 5 |
| GPT | 5.6 Sol / Terra / Luna、5.5、5.4、5.3 Codex |
| GLM | 5.3、5.3 Flash、5.2、5v Turbo |
| Kimi / MiniMax | K3、K2.7 Code、K2.6；MiniMax M3 |
| Gemini / DeepSeek | Gemini 3.5 Flash；DeepSeek V4 Flash / Pro |

High、Max 和 1M context 是客户端显示的推理或上下文规格，不必然对应不同模型 id。没有明确独立 ID 时，不要自行拼接后缀。GLM-5.3-Flash、GLM-5v-Turbo 在本次核对的上游目录中尚未出现，需要上游提供后再验证上线。

### 价格单位

输入、输出和缓存按页面标注的每百万 Token 单价计费；套餐额度沿用平台金额计价单位，不是保证固定 Token 数。长上下文、缓存、协议和渠道可能影响实际价格，查看请求对应价格快照与最终结算。

## 钱包、订阅与账单

### 两种计费方式

| 项目 | 说明 |
| --- | --- |
| 钱包密钥 | 使用现金/赠送余额，受钱包可用额与密钥额度上限约束 |
| 订阅密钥 | 绑定具体订阅周期，受套餐额度、到期时间与模型权限约束 |
| 调整余额 | 改变钱包账目，不增加订阅周期额度 |
| 设置订阅 | 按操作开通新周期、追加赠送额度或更换套餐，不伪造支付收入 |

同一用户可以拥有不同计费方式的密钥。充值钱包不会自动补充订阅密钥；开通订阅不会把旧钱包密钥转换成订阅密钥。后台赠送不产生真实支付收入或推广佣金。

### 预占与结算

调用前按估算金额冻结，收到上游用量后结算并释放差额。在途请求、异常对账和退款审查可能使额度保持冻结；不要直接改数据库金额解冻。使用记录里保留请求 ID、计费类型及结算状态，异常由运营台核对。

### 毛利提示的含义

上游成本、售价、返佣和实际现金收入是不同口径。同步定价按配置的成本与利润保护生成售价；上游成本更新、历史价格、赠送和套餐实收差异可能导致报表低于目标。管理员应先同步并核对价格、汇率、佣金和请求时间，再处理异常。定价目标不等于企业净利润保证。

平台 HAI 上游余额属于平台采购账户，用户钱包和订阅属于客户权益。上游仍有余额不能说明某个客户的钱包仍有可用额。

## 用户、代理商与运营台

超级管理员使用独立运营身份登录。普通用户与代理商采用独立菜单管理；代理商资格影响渠道业务，不等于后台管理权限。

1. 普通用户：新增用户、查看详情、暂停/恢复、调整余额、设置订阅。
2. 代理商：新增代理商账户、管理渠道政策与客户关系、检查结算状态。
3. 价格版本：同步上游并应用零售价；人工变更填写原因并保留版本审计。
4. 账单对账与运营告警：核对冻结资金、请求结算和上游额度，处理后复查。
5. 支付订单、邀请与提现：以实收、退款和已结算奖励为依据，不能把赠送额度视为收入。
6. 操作日志：所有资金、身份和关键配置变更都应能追溯到操作人及原因。

套餐追加和更换受来源、旧周期余量、冻结额等限制。界面拒绝时先查在途请求或付费权益，不能用余额调整绕过保护。

## 短信通知与收件人

| 项目 | 说明 |
| --- | --- |
| 登录/找回验证码 | 经校验的当前登录或找回手机号 |
| 开户、暂停/恢复、余额、订阅、密码变更 | 被操作账户手机号 |
| 代理商资格变更 | 代理商所属用户手机号 |
| 密钥额度、客户钱包余额 | 该密钥或钱包所属用户，需验证手机号并开启额度提醒 |
| HAI 上游额度、严重平台运营告警 | 已启用且符合固定身份规则的超级管理员 |

用户手机号缺失、关闭额度提醒或网关发送失败，不会改发给管理员。未知告警类型不自动归类为管理员短信。钱包告警只评估有效钱包计费密钥，订阅额度单独计算。

### 收到提醒后

先判断短信写的是平台上游、个人钱包还是密钥额度。用户额度问题查看自己的平台账户；上游问题由超级管理员在运营台核对。短信为通知，实际余额和状态以平台为准。

短信网关接受提交不等于手机已经送达。管理员需要结合投递日志的脱敏收件人、purpose、状态和时间检查；不应通过批量发送真实短信进行开发测试。

## 常见问题与排障

| 项目 | 说明 |
| --- | --- |
| 401 | 检查密钥、认证头、到期/停用状态以及是否把登录凭证当成 API Key |
| 403 / 模型不允许 | 核对账户状态、模型支持范围、密钥权限与套餐范围 |
| 402 / 额度不足 | 检查该密钥的计费方式、可用额度和冻结额；上游余额不能代替用户额度 |
| 404 / 路由不支持 | 核对 Base URL、是否重复 /v1，以及模型支持的协议 |
| 429 | 检查 RPM、并发、密钥额度策略或上游限流，使用退避重试 |
| 502 / 503 / 504 | 核对平台状态、上游错误、Adapter 进程与网络；携带请求 ID 排查 |

错误码会因上游与客户端封装有所不同，以响应 error 和平台请求记录为准。不要无限重试付费请求，也不要为了绕过权限不断生成新密钥。

### 提交问题时提供

1. 发生时间、客户端名称与版本、操作系统。
2. 模型精确 ID、接口路径、是否流式、HTTP 状态及 Trace / Request ID。
3. 脱敏错误信息和最小复现步骤，绝不附真实密钥或短信验证码。

## 系统部署配置

本项目由 Next.js 前端、NestJS 服务端、MySQL、Redis、CAP 人机验证、托管 Adapter 与 Caddy 组成。生产使用 deploy/compose.yml。以下只解释配置职责，不公开真实凭证。

| 项目 | 说明 |
| --- | --- |
| PUBLIC_HOST / PUBLIC_ALIAS_HOST | 主站和别名域名，DNS 指向部署服务器 |
| DB_* / MYSQL_* | 数据库连接与初始化账户，区分应用密码和 root 密码 |
| HAI 管理/推理配置 | 按 server/.env.example 配置，管理查询与推理凭证各司其职 |
| MESSAGE_GATEWAY / MESSAGE_ACCOUNT / MESSAGE_PWD / MESSAGE_SIGNATURE | 短信网关、账户、密码及已审核签名 |
| CAP_* | 人机验证站点参数与密钥 |
| 支付配置 | 按 docs/PAYMENT_SETUP.md 配置回调地址、商户证书与密钥 |
| ADAPTER_OPS_TOKEN | 托管 Adapter 运维认证，不分发给客户 |

### 发布与验收

1. 根据 deploy/.env.example 和 server/.env.example 准备生产环境；密钥不提交 Git。
2. 发布前备份数据库，检查迁移和测试结果；不要对已有业务库重复导入初始化 schema。
3. 执行 deploy/update.sh，确认目标提交、容器状态与 /api/health/ready。
4. 验证登录、模型目录、客户端配置页面和一次受控调用；仅 HTTP 401 探测不足以确认真实推理。
5. 为 docs.protonkener.com 添加 DNS A 记录指向同一服务器，放通 80/443，Caddy 自动申请证书。
6. 失败时按变更范围回滚应用并核对数据库兼容性，保留业务账本和审计记录。

### 短信配置维护

完整模板见仓库 docs/SMS_TEMPLATES.md。服务端本地替换变量，再提交短信网关；未替换占位符会阻止发送。生产缺少短信配置会报错，不会降级到管理员号码。修改签名或内容后按供应商要求办理审核，不能把本地模板文件变更当作供应商审核已经通过。