创建 API Key

适用对象：已经完成注册并能登录 Pragma 的用户。完成本页后，你应该能创建自己的 API Key，知道不同客户端的 Base URL 怎么填，并用最小 /v1/models 请求确认 Key 可用。

先确认这三件事

• API Key 只用于本地 agent、客户端、SDK 或 OpenAI-compatible API 调用。
• 站内在线聊天和在线画图登录后直接使用，不需要手动填写 API Key。
• Key 只展示给你自己看，不要发给他人，也不要提交到公开仓库。

1注册 / 登录进入 Pragma 主站并确认能打开控制台2创建 API Key保存自己的 Key，并完成 /v1/models 最小验证3选择入口网页端直接使用；本地客户端按协议选择 Base URL4短任务验收先发短消息或查模型列表，再开始长上下文任务

什么情况下需要 API Key

你的目标	是否需要 API Key	下一步
在网页里聊天或画图	不需要手动创建	直接看 在线聊天与画图
配置 Codex CLI、Claude Code 或 Cherry Studio	需要	先完成本页，再看对应客户端页面
用 OpenAI SDK、脚本或本地 agent 调用 Pragma	需要	创建 Key 后执行最小验证
只是查看文档或服务状态	不需要	继续阅读文档即可

如果你还没有账号，请先回到 注册与登录。

创建前需要知道什么

开始前请确认：

• 你已经能登录 https://pragma.academic-ruc.cc。
• 当前打开的是 Pragma 主站，不是文档站。
• 你有一个安全保存 Key 的地方，例如密码管理器或只保存在本机的配置文件。
• 你知道自己要配置哪个客户端。不同客户端的 Base URL 可能不同。

不要为了测试把真实 Key 发到群聊、截图、issue、公开代码仓库或任何他人可见的位置。

如何创建 API Key

1. 打开 https://pragma.academic-ruc.cc/login 并登录。
2. 进入 API Key 页面：https://pragma.academic-ruc.cc/keys。
3. 点击创建按钮，按页面提示生成新的 Key。
4. 如果页面支持备注或名称，写一个能让你以后认出来的名字，例如 codex-laptop 或 cherry-studio。
5. 复制生成的 Key。Key 通常以 sk- 开头。
6. 立刻把 Key 保存到你自己的安全位置。

页面可能不会再次完整显示这个 Key。如果你没有保存，只能删除旧 Key 后重新创建。

生成后立刻做什么

建议按这个顺序处理：

API Key 创建后先验证

不要把真实 Key 放进截图、公开仓库或聊天记录。

请求地址https://pragma.academic-ruc.cc/v1/models

AuthorizationBearer sk-your-key

成功信号返回模型列表

1. 保存 Key。
2. 完成最小 /v1/models 验证。
3. 再去配置客户端。

不要一边复制 Key，一边打开多个聊天窗口或多个配置文件反复粘贴。先确认 Key 本身有效，再进入具体客户端配置，会更容易排查问题。

推荐配置怎么填

OpenAI-compatible 客户端、OpenAI SDK、Codex CLI、Cherry Studio 等通常使用下面这组配置：

OpenAI-compatible需要末尾 /v1

https://pragma.academic-ruc.cc/v1

Cherry Studio、Codex CLI、OpenAI SDK 等客户端使用。

Claude Code 直连不要写 /v1

https://pragma.academic-ruc.cc

Claude Code 会自己拼接 /v1/messages。

图像 API文本和图像分开

https://image.academic-ruc.cc/v1

客户端图像 API 或 image-gen skill 使用。

配置项	值
Provider 类型	OpenAI Compatible / OpenAI
Base URL	https://pragma.academic-ruc.cc/v1
API Key	你自己创建的 sk-your-key

这里的 sk-your-key 是占位符。实际配置时换成你自己的 Key，不要把真实 Key 写进文档、截图或公开代码。

如何完成最小验证

创建 Key 后，先验证模型列表：

配置后验收先短测，再长任务

1. 保存 Key

   Key 生成后立即保存到自己的安全位置。

2. /v1/models

   返回模型列表，说明基础链路可用。

3. 再配客户端

   验证通过后再进入 Cherry、Codex 或 Claude Code。

macOS / Linux（bash / zsh）先把 Key 存进临时变量，避免反复粘贴：

export PRAGMA_KEY=sk-your-key
curl https://pragma.academic-ruc.cc/v1/models \
  -H "Authorization: Bearer $PRAGMA_KEY"

Windows PowerShell 用户请写成单行，不要保留末尾的 \ 续行符：

$env:PRAGMA_KEY = "sk-your-key"
curl https://pragma.academic-ruc.cc/v1/models -H "Authorization: Bearer $env:PRAGMA_KEY"

如果返回模型列表，说明：

• Base URL 可访问；
• API Key 已被正确识别；
• OpenAI-compatible 入口基本可用。

如果返回 401，通常是 Key 错误、复制不完整、Key 已删除，或 Authorization 没有填对。先重新复制自己的 Key，再确认命令里没有多余空格或换行。

不同客户端怎么选 Base URL

客户端或用途	Base URL	继续阅读
Cherry Studio	https://pragma.academic-ruc.cc/v1	Cherry Studio
Codex CLI	https://pragma.academic-ruc.cc/v1	Codex CLI
OpenAI SDK / OpenAI-compatible API	https://pragma.academic-ruc.cc/v1	本页最小验证
Claude Code 直连	https://pragma.academic-ruc.cc	Claude Code
站内聊天 / 站内画图	不需要手动填写	在线聊天与画图

Claude Code 直连是特殊情况。它走 Anthropic Messages 协议，Base URL 不要带 /v1：

ANTHROPIC_BASE_URL=https://pragma.academic-ruc.cc
ANTHROPIC_AUTH_TOKEN=sk-your-key

如果写成 https://pragma.academic-ruc.cc/v1，Claude Code 可能拼出 /v1/v1/messages，导致 404。

常见问题

页面不再完整显示 Key 怎么办？

如果你没有保存，只能删除旧 Key 后重新创建。不要试图从截图、浏览器历史或别人发来的消息里找回 Key。

/v1/models 返回 401 是什么？

通常表示认证失败。请检查：

1. Key 是否复制完整。
2. Key 是否仍然存在。
3. Authorization 是否写成 Bearer sk-your-key。
4. 命令里是否混入空格、换行或中文引号。

/v1/models 返回 404 是什么？

最常见原因是 URL 拼错。OpenAI-compatible 验证应该使用：

https://pragma.academic-ruc.cc/v1/models

Claude Code 用户则不要把 ANTHROPIC_BASE_URL 写成带 /v1 的地址。

站内聊天和画图需要 API Key 吗？

不需要手动填写。登录后进入 /apps/chat 或 /apps/images 即可使用。详细说明见 在线聊天与画图。

我能把 Key 给同学共用吗？

不建议。每个人应使用自己的 Key，方便查看用量和排查问题。怀疑泄露时，请删除旧 Key 并重新创建。

下一步

目标	推荐页面
我想先在网页里使用	在线聊天与画图
我想配置 Codex CLI	Codex CLI
我想配置 Claude Code	Claude Code
我想配置 Cherry Studio	Cherry Studio
我遇到错误码或服务状态问题	故障排查