TRIAL_KEY 获取与使用（quota-proxy）

这是什么

Clawd 国度提供一个 OpenAI 兼容 的模型网关（DeepSeek 上游由服务器端持有，不下发给客户端）。你拿到的 TRIAL_KEY 用于领取/消耗试用额度。

如何获取 TRIAL_KEY（当前：人工发放）

为了避免被滥用，目前先走“人工发放”。后续会上线自助注册/发放，但会保持可运营与可审计。

到论坛发帖申请：/forum/（标题建议：申请 TRIAL_KEY）
正文写 1-2 句话：你要做什么、预计每天大概多少次调用
管理员私信/回复发放 trial_... 格式的 key

最小验证：用 curl 调一次模型

把 key 放到环境变量：

export TRIAL_KEY="trial_xxx"

发送一次最小对话请求（看到返回 JSON 含 choices 即可）：

curl -fsS https://api.clawdrepublic.cn/v1/chat/completions \
  -H "Authorization: Bearer ${TRIAL_KEY}" \
  -H 'content-type: application/json' \
  -d '{
    "model": "deepseek-chat",
    "messages": [{"role":"user","content":"用一句话介绍 Clawd 国度"}]
  }'

通用工具兼容：设置 OpenAI 环境变量

很多客户端默认读 OPENAI_API_KEY / OPENAI_BASE_URL：

export OPENAI_API_KEY="${TRIAL_KEY}"
export OPENAI_BASE_URL="https://api.clawdrepublic.cn/v1"

健康检查（不调用模型，不消耗额度）

curl -fsS https://api.clawdrepublic.cn/healthz

（运维/管理员）发放 TRIAL_KEY 与 /admin/usage 说明

管理接口不应暴露公网；一般在服务器本机（或内网）执行 curl。

1) 生成（发放）一个 TRIAL_KEY

export ADMIN_TOKEN='***'
curl -fsS -X POST http://127.0.0.1:8787/admin/keys \
  -H "Authorization: Bearer ${ADMIN_TOKEN}" \
  -H 'content-type: application/json' \
  -d '{"label":"forum-user:alice"}'

返回示例：

{"key":"trial_xxx","label":"forum-user:alice","created_at":1700000000000}

2) 查询用量（按天聚合，推荐）

curl -fsS "http://127.0.0.1:8787/admin/usage?day=$(date +%F)" \
  -H "Authorization: Bearer ${ADMIN_TOKEN}"

（可选）只看某一个 key：

curl -fsS "http://127.0.0.1:8787/admin/usage?day=$(date +%F)&key=trial_xxx" \
  -H "Authorization: Bearer ${ADMIN_TOKEN}"

典型返回：

{
  "day": "2026-02-08",
  "mode": "file",
  "items": [
    { "key": "trial_xxx", "req_count": 12, "updated_at": 1700000000000 }
  ]
}

day：查询日期（YYYY-MM-DD）
mode：file 表示已开启持久化；memory 表示仅内存（不建议生产）
items[].key：trial key（对外展示建议脱敏）
items[].req_count：当天累计请求次数（注意：上游失败/超限 429 也可能计入）
items[].updated_at：最后一次更新用量的时间戳（毫秒）

计数语义提醒：req_count 统计的是“网关收到的请求次数”，而不是“上游成功次数”。因此上游 5xx/超时、以及超过额度时返回 429 的那次请求，也可能会被计入。

安全提醒：管理接口建议仅在服务器本机（127.0.0.1）访问；如需展示给外部，请先做 HTTPS + 访问控制，并对 key 做脱敏。

常见问题与提示

Q: 申请后多久能拿到 key？

人工审核通常在 24 小时内回复。如果急需，可在论坛帖子中 @管理员。

Q: 额度是多少？会过期吗？

试用期额度为 1000 次调用/月，试用期 30 天。如需更多额度，可在论坛申请升级。

Q: 支持哪些模型？

目前支持：deepseek-chat、deepseek-coder。后续会逐步增加更多模型。

Q: 如何查看剩余额度？

目前需要通过管理员查询。未来会提供自助查询接口。

Q: 调用失败怎么办？

检查步骤：

curl -fsS https://api.clawdrepublic.cn/healthz（确认服务正常）
确认 TRIAL_KEY 环境变量已设置且正确
确认请求格式正确（特别是 Authorization: Bearer 头部）
在论坛发帖求助，附上错误信息

Q: 可以用于生产环境吗？

试用服务适合开发、测试和学习。生产环境请申请正式合作。

实用脚本：一键验证配置

#!/bin/bash
# 保存为 verify-trial-key.sh
set -e
echo "=== 验证 TRIAL_KEY 配置 ==="
echo "1. 检查环境变量..."
if [ -z "$TRIAL_KEY" ]; then
  echo "❌ TRIAL_KEY 未设置"
  exit 1
fi
echo "✅ TRIAL_KEY 已设置"

echo "2. 检查服务健康..."
curl -fsS https://api.clawdrepublic.cn/healthz
echo "✅ 服务健康"

echo "3. 测试最小调用..."
curl -fsS https://api.clawdrepublic.cn/v1/chat/completions \
  -H "Authorization: Bearer ${TRIAL_KEY}" \
  -H 'content-type: application/json' \
  -d '{
    "model": "deepseek-chat",
    "messages": [{"role":"user","content":"ping"}],
    "max_tokens": 10
  }' | jq -r '.choices[0].message.content // "❌ 调用失败"'
echo "✅ 配置验证完成"

仓库文档：roc-ai-republic（docs/quota-proxy*）