OpenAI-compatible需要末尾 /v1
https://pragma.academic-ruc.cc/v1Cherry Studio、Codex CLI、OpenAI SDK 等客户端使用。
深浅色
客户端配置总览
本页用于判断你该读哪一页、Base URL 应该填哪一个。
第一次配置时，先完成：
然后再选择具体客户端。
Claude Code 直连不要写 /v1
https://pragma.academic-ruc.ccClaude Code 会自己拼接 /v1/messages。
图像 API文本和图像分开
https://image.academic-ruc.cc/v1客户端图像 API 或 image-gen skill 使用。
先判断你要做什么
| 目标 | 推荐页面 | 需要 API Key | 说明 |
|---|---|---|---|
| 只想在网页里聊天 | 在线聊天与画图 | 不需要手动填写 | 登录后直接使用站内入口 |
| 只想在网页里画图 | 在线聊天与画图 | 不需要手动填写 | 优先用站内画图入口 |
| 用 Cherry Studio | Cherry Studio | 需要 | 适合图形化桌面客户端 |
| 用 Codex CLI | Codex CLI | 需要 | 适合 coding agent CLI |
| 用 Claude Code | Claude Code | 需要 | Base URL 不要带 /v1 |
| 不知道该用 RTK、cache-fix 还是直连 | 省 token 决策中心 | 视认证方式而定 | 按客户端、认证、系统和入口选择，不要求所有人安装全部组件 |
Claude Code 长会话额度掉得快 / --resume 后像重新付费 | Claude Code 缓存优化 | 需要 | 只针对 Claude Code 请求层；Codex 用户看 RTK |
| 给 agent 配本地图像 skill | 图像生成与 skill | 需要 | 适合自动化文生图流程 |
| 降低 agent 命令输出 token | RTK 省 token 配置 | 视场景而定 | 只处理本机命令输出压缩 |
配置前准备
- 确认你能登录
https://pragma.academic-ruc.cc。 - 在控制台创建自己的 API Key。
- 保存 API Key 后立即做最小验证。
- 根据客户端类型选择正确的 Base URL。
最小验证见 创建 API Key。如果 /v1/models 能返回模型列表，说明 Key 和基础网络路径可用。
Base URL 速查
上面的卡片适合快速复制；下面的表格保留完整文字版，方便搜索和对照。
| 用途 | Base URL |
|---|---|
| OpenAI-compatible 客户端 | 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。
OpenAI-compatible 客户端
Codex CLI、Cherry Studio、OpenAI SDK 这类客户端通常使用 OpenAI-compatible 协议。
关键配置：
| 配置项 | 值 |
|---|---|
| Base URL | https://pragma.academic-ruc.cc/v1 |
| API Key | 你在 pragma 创建的 sk-... |
| 模型 | 以控制台或模型列表实际可见为准 |
配置后先测试模型列表，再发一条短消息。不要一开始就跑长上下文 agent 任务。
Claude Code 直连
Claude Code 直连接入 pragma 时，通常走 Anthropic Messages 协议。
关键配置：
| 配置项 | 值 |
|---|---|
ANTHROPIC_BASE_URL | https://pragma.academic-ruc.cc |
ANTHROPIC_AUTH_TOKEN | 你在 pragma 创建的 sk-... |
Claude Code 会自己拼接 /v1/messages，所以 ANTHROPIC_BASE_URL 末尾不要写 /v1。
图像相关入口
| 场景 | 推荐入口 |
|---|---|
| 登录后在网页画图 | https://pragma.academic-ruc.cc/apps/images |
| 独立图像工作台 | https://image.academic-ruc.cc/ |
| 客户端图像 API | https://image.academic-ruc.cc/v1 |
| 本地 agent 自动画图 | 图像生成与 skill |
图像生成不是流式接口，等待时间通常比聊天更长。不要因为几十秒没有返回就连续重复提交。
配置后怎么验收
配置后验收先短测，再长任务
- 模型列表
能看到当前可用模型。
- 短消息
发送“请只回复 OK”能返回。
- 错误入口
401 / 403 / 404 先回到 FAQ。
| 验收项 | 成功信号 |
|---|---|
| API Key | /v1/models 返回模型列表 |
| Cherry Studio | 模型列表测试成功，短消息可回复 |
| Codex CLI | 短任务能正常返回 |
| Claude Code | “请只回复 OK” 能正常返回 |
| 在线应用 | 登录后能进入聊天或画图页面 |
如果模型列表能返回，但复杂任务失败，优先检查上下文长度、模型选择、reasoning / effort 设置和客户端版本。
常见错误入口
| 表现 | 先看 |
|---|---|
| 401 / 403 / 404 / 429 / 521 | 故障排查 |
| 服务疑似不可用 | 故障排查 |
| 浏览器或客户端打不开域名 | 故障排查 |
| 不确定能不能分享 Key | 使用规范 |
下一步
| 我想做什么 | 下一页 |
|---|---|
| 创建或验证 Key | 创建 API Key |
| 配 Cherry Studio | Cherry Studio |
| 配 Codex CLI | Codex CLI |
| 配 Claude Code | Claude Code |
| 直接用网页 | 在线聊天与画图 |