快速开始

先按你的使用目标选择入口。只想聊天、写作、翻译或分析内容时，不需要配置开发工具；只有需要编程或在其他软件中调用模型时，才需要创建 API Key。

内置聊天无需安装或创建 API Key，登录即可对话Windows选择 Claude Code、Codex、Pi 或 CursormacOS选择 Claude Code、Codex、Pi 或 CursorAPI 参考鉴权、端点与调用示例故障排查快速定位连接与配置问题切换多个 API Key使用 CC Switch 管理个人、工作与测试配置其他兼容客户端国内客户端、Cursor 与更多接入方式

零基础首选：直接使用内置聊天

没有编程经验或 AI 使用经验

直接使用 悠然 AI 内置聊天。它已经接好模型，不需要安装软件，不需要理解 Base URL，也不需要手动创建 API Key。

1. 如果还没有账号，请联系管理员创建一个普通用户账号。管理员账号不能进入聊天。
2. 打开 悠然 AI 内置聊天，输入管理员提供的用户名和初始密码。
3. 首次登录时按页面提示设置新密码。新密码会同时用于聊天和控制台。
4. 保持默认模型，直接在输入框中描述你的需求并发送。你也可以粘贴或上传图片。

例如，可以直接输入：

• “帮我把这段话改得更礼貌，适合发给客户。”
• “用完全不懂技术的人也能理解的方式，解释什么是云计算。”
• “总结这张图片中的重点，并整理成待办清单。”

聊天会自动保存会话，方便你换设备后继续使用。模型选择、回答语言、详略程度和其他偏好可以稍后在“设置”中调整，第一次使用时保持默认即可。更多说明见内置聊天使用指南与隐私。

开发者路径：接入工具前准备

1. 登录 悠然 AI 控制台，完成首次密码修改。
2. 确认使用方式。新建普通用户默认启用按量计费，并获得 $10 初始额度和 $5 每日限额；已分配席位的用户也可以使用已生效的席位订阅。
3. 在访问密钥页面创建一把独立的 API Key。
4. 确认 OpenAI 兼容工具使用以下 Base URL：

OpenAI Base URL复制

https://youran-ai.du-fu.com/v1

Claude Code 会自行追加 /v1/messages，因此它的 ANTHROPIC_BASE_URL 应填写 https://youran-ai.du-fu.com。

妥善保管 API Key

API Key 与密码具有相同敏感度。只保存在操作系统的用户级环境变量或个人配置中，不要写进项目文件、聊天记录或 Git 仓库。

最短验证路径

先通过模型列表确认当前可用的模型 ID：

Shell复制

curl -sS https://youran-ai.du-fu.com/v1/models \
  -H "Authorization: Bearer <YOURAN_API_KEY>"

返回结果中的 data[].id 才是应写入客户端配置的模型 ID。模型列表可能变化，文档不会硬编码固定名称。

不知道选哪个模型？

先去模型怎么选看三档模型的聪明程度、速度和价格对比。新手默认选 gpt-5.6-terra 即可。

选择客户端

• 内置聊天：适合不想安装或配置软件的用户，登录普通用户账号即可使用，不需要手动创建 API Key。
• Claude Code：通过 /v1/messages 使用 Anthropic Messages 协议，但实际模型由悠然 AI 提供，当前仅支持 GPT 系列模型。
• Codex 终端版：通过 /v1/responses 使用 OpenAI Responses API，并以自定义 youran Provider 连接。
• Codex 桌面版：在 ChatGPT 桌面应用中运行，与终端版共享用户级配置，但需要单独处理桌面进程的 API Key 读取。
• Pi：终端里的极简 AI 编程助手，通过 models.json 声明悠然 AI 为自定义 Provider，见 Windows：Pi 或 macOS：Pi。
• Cursor：通过自带 API Key 与 OpenAI Base URL 覆盖接入，具体兼容范围以客户端当前版本为准。
• 其他客户端：支持自定义 OpenAI Base URL、Bearer API Key 和模型 ID 的客户端，可参考其他兼容客户端接入。