深浅色
故障排查
先按症状定位问题，再做最小验证；仍无法解决时，用本页末尾的安全反馈模板联系管理员。
三步先验收
- 看服务状态：打开
https://status.academic-ruc.cc/，确认主站、API 或相关分组不是红色。 - 对 Base URL：Claude Code 不带
/v1；
其他兼容客户端带/v1。 - 做短验证：Key 用户先跑
/v1/models；
客户端用户先发“请只回复 OK”。
如果这三步都正常，但长任务仍失败，优先降低上下文长度、减少并发 agent，再继续排查。
按症状处理
打不开主站或域名
可能是服务异常、本地 DNS、代理软件或网络缓存。先看 服务状态；如果状态页正常且只有你打不开，再看 DNS 修复。
401 / API Key
通常是 Key 错误、复制不完整、Key 已删除或认证字段错误。回到 创建 API Key 做最小验证，再重新复制或重建自己的 Key。
403 / 权限
通常是 Key 权限不足或端点不匹配。确认你使用的是自己的 Pragma Key；仍失败时联系管理员。
404 / Base URL
通常是 URL 拼错或 Base URL 类型混用。对照 客户端配置总览：Claude Code 去掉 /v1；OpenAI-compatible 客户端补上 /v1。
429 / 频率或并发
通常是请求过密、并发过多或短时间重复重试。先停止连续重试，减少并发，等一段时间后用短任务重试；持续出现再联系管理员。
5xx / 521
通常是服务端、Cloudflare 回源或上游临时异常。先看 服务状态；状态异常时等待恢复，不要持续重试。
首 token 慢或超时
常见原因是上下文长、reasoning / effort 高、日志太多或并发 agent 多。新开会话，先发一个短任务；短任务正常后再逐步恢复复杂任务。
Claude Code 长会话额度掉得快
如果你经常 --resume 恢复旧会话、MCP/Skills 很多、或者长会话额度消耗比预期快，这通常不是 Pragma 服务端计费问题，而是 Claude Code 请求层缓存不稳定。
先区分两件事：
- 不确定该装什么：先看 省 token 决策中心。
- 命令输出太长：看 RTK 省 token 配置。
- Claude Code resume/cache 不稳：看 Claude Code 缓存优化。
生图慢或提示暂无上游
图像不是流式返回，图像上游也可能暂时不可用。等待当前任务完成，不要重复提交；需要进一步判断时，先区分你用的是站内画图还是图像 API，再看 在线聊天与画图。
仍无法判断
按下面模板整理问题，再联系管理员。不要粘贴敏感信息。
Base URL 速查
| 场景 | Base URL |
|---|---|
| Cherry Studio / Codex CLI / OpenAI SDK | https://pragma.academic-ruc.cc/v1 |
| Claude Code 直连 | https://pragma.academic-ruc.cc |
| 图像 API 客户端 | https://image.academic-ruc.cc/v1 |
不要把三类地址混用。最常见错误是给 Claude Code 填了 /v1，或者给 OpenAI-compatible 客户端漏掉 /v1。
联系管理员前准备
不要粘贴 API Key、密码、完整 Authorization 头、Bearer token、Cookie、完整请求体、完整响应体、后台截图、包含账号信息的截图、完整终端日志或控制台粘贴。Key 如需举例只写成
sk-***。 只复制下面这个模板，并按实际情况填写。不要自动收集配置文件、环境变量或终端日志。
text
【Pragma 故障反馈】
时间：
使用入口：[网页聊天 / 网页画图 / Cherry Studio / Codex CLI / Claude Code / OpenAI SDK / 图像 API]
系统与客户端版本：[例如 Windows + Cherry Studio 版本；不知道可写“不清楚”]
症状一句话：
错误码或提示：[401 / 403 / 404 / 429 / 5xx / 521 / 超时 / 暂无上游 / 其他]
Base URL 类型：[OpenAI-compatible / Claude Code 直连 / 图像 API / 不确定]
模型名：
状态页颜色：[全绿 / 有红色 / 有黄色 / 打不开]
最小验证结果：[/v1/models 成功或失败；短消息是否能回复]
已经尝试过：
补充说明：下面保留常见问题短答，方便搜索错误码和关键词。
我不知道该读哪一页
| 目标 | 先看 |
|---|---|
| 第一次注册 | 注册与登录 |
| 创建或验证 Key | 创建 API Key |
| 不知道客户端怎么选 | 客户端配置总览 |
| 只想网页聊天或画图 | 在线聊天与画图 |
| 服务疑似异常 | 服务状态 |
| 本机打不开域名 | DNS 修复 |
API Base URL 到底填哪个？
| 客户端 | Base URL |
|---|---|
| Codex CLI / Cherry Studio / OpenAI SDK | https://pragma.academic-ruc.cc/v1 |
| Claude Code 直连 | https://pragma.academic-ruc.cc |
| 图像 API 客户端 | https://image.academic-ruc.cc/v1 |
完整说明见 客户端配置总览。创建 Key 和最小验证见 创建 API Key。
401 是什么？
通常是 API Key 错误、复制不完整、Key 已删除或没有填认证字段。
处理：
- 重新复制自己的 Key。
- 确认 Key 以
sk-开头。 - 不要多复制空格或换行。
- 仍失败时，回到 创建 API Key 重新做最小验证。
403 是什么？
通常是权限不足，例如当前 Key 没有对应端点权限。
处理：
- 确认你用的是自己的 Pragma Key。
- Claude Code 用户确认没有把 Base URL 写错。
- 仍失败则联系管理员。
404 是什么？
最常见原因是 URL 拼错。
Claude Code 特别注意：
text
正确：ANTHROPIC_BASE_URL=https://pragma.academic-ruc.cc
错误：ANTHROPIC_BASE_URL=https://pragma.academic-ruc.cc/v1Codex CLI、Cherry Studio、OpenAI SDK 这类 OpenAI-compatible 客户端则要使用 https://pragma.academic-ruc.cc/v1。
429 是什么？
429 通常表示短时间内请求过密、并发过多或重复重试太频繁。
处理：
- 先停止连续重试。
- 关闭多余 agent 或客户端。
- 等一段时间后，用短任务重新验证。
- 如果持续出现，带上安全反馈模板联系管理员。
不要根据 429 猜测具体配额或渠道池状态；公开文档不提供这类运维细节。
521 是什么？
521 通常表示浏览器连接到了 Cloudflare，但 Cloudflare 回源到服务器失败。先等待几分钟，再联系管理员确认主站状态。
如何确认是不是服务挂了？
先打开服务状态页：
text
https://status.academic-ruc.cc/绿色表示服务正常，红色表示对应服务不可用，黄色表示降级或维护。横向心跳条是最近探测历史，越靠右越新。详细解释见 服务状态 页面。
为什么首 Token 有时很慢？
不一定是网站入口慢。常见原因：
- 上下文太长。
- reasoning / effort 太高。
- 同时开了多个 agent。
- 请求里包含大量日志或文件。
- 上游住宅代理正在抖动。
先尝试新开会话、减少上下文、降低 reasoning。
Claude Code 长会话为什么像重新付费？
先确认是不是命令输出太长。如果是 git diff、测试日志、docker logs 很长，看 RTK 省 token 配置。
如果是 --resume、MCP、Skills、Hooks 后长会话额度异常，看 Claude Code 缓存优化。
生图为什么比聊天慢很多？
图像生成不是流式接口，必须等整张图生成完成才返回。几十秒到数分钟都可能正常。
站内画图入口和常见提示见 在线聊天与画图。
如果你在客户端里配置图像 API，请同时确认图像 Base URL 是 https://image.academic-ruc.cc/v1，不是文本 API 地址。
提示暂无可用上游怎么办？
这通常表示当前图像或模型上游暂时不可用。先不要连续重复提交，等待一段时间后用短任务重试。如果持续出现，请说明你使用的是网页端、客户端文本接口还是图像 API。
我能把 API Key 给同学共用吗？
不建议。每个人应使用自己的 Key，方便追踪用量和排查问题。Key 泄露后请立刻删除并重建。
文档里为什么没有管理员后台信息？
这是用户使用文档，不包含后台账号、Master Key、VPS、代理、数据库和运维细节。这些信息只保留在内部运维文档中。